Springfox项目深度解析：Swagger文档生成配置指南

Springfox项目深度解析：Swagger文档生成配置指南

springfox Automated JSON API documentation for API's built with Spring 项目地址: https://gitcode.com/gh_mirrors/sp/springfox

一、Springfox简介

Springfox是一个用于Spring框架的Swagger集成库，能够自动生成API文档。它通过扫描Spring应用程序中的控制器和模型，生成符合Swagger规范的API描述，为开发者提供交互式API文档和测试界面。

二、基础配置

2.1 启用Swagger支持

根据不同的Swagger规范版本，Springfox提供了不同的启用注解：

// 启用Swagger 1.2规范支持
@EnableSwagger

// 启用Swagger 2.0规范支持
@EnableSwagger2

2.2 Docket核心配置

Docket是Springfox的核心配置类，用于定义API文档的分组和筛选规则。其名称来源于法律术语，意为"文档摘要"，恰如其分地描述了它的功能。

典型配置示例：

@Bean
public Docket customDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("business-api")  // API分组名称
        .select()
            .apis(not(withClassAnnotation(CustomIgnore.class)))  // 按控制器筛选
            .paths(paths())  // 按路径筛选
            .build()
        .apiInfo(apiInfo())  // API基本信息
        .securitySchemes(securitySchemes())  // 安全方案
        .securityContext(securityContext());  // 安全上下文
}

// 路径筛选器
private Predicate<String> paths() {
    return or(
        regex("/business.*"),
        regex("/some.*"),
        regex("/contacts.*"));
}

三、高级配置技巧

3.1 ObjectMapper配置

Springfox使用Jackson的ObjectMapper来序列化Swagger模型。可以通过监听ObjectMapperConfigured事件来定制ObjectMapper：

@Component
public class ObjectMapperConfigurer implements ApplicationListener<ObjectMapperConfigured> {
    @Override
    public void onApplicationEvent(ObjectMapperConfigured event) {
        ObjectMapper objectMapper = event.getObjectMapper();
        // 自定义ObjectMapper配置
    }
}

3.2 自定义API文档端点

默认情况下，Swagger文档的访问路径如下：

| Swagger版本 | 文档路径 | 说明 | |------------|-----------------------|------------------| | 1.2 | /api-docs | 默认分组 | | 1.2 | /api-docs?group=分组名 | 指定分组 | | 2.0 | /v2/api-docs | 默认分组 | | 2.0 | /v2/api-docs?group=分组名 | 指定分组 |

可以通过配置文件修改这些路径：

# 修改Swagger 1.2文档路径
springfox.documentation.swagger.v1.path=/custom-api-docs

# 修改Swagger 2.0文档路径
springfox.documentation.swagger.v2.path=/custom/v2/api-docs

3.3 延迟启动配置

在某些框架(如Grails)中，可能需要延迟Springfox的启动：

# 禁用自动启动
springfox.documentation.auto-startup=false

禁用后需要手动启动：

@Autowired
private DocumentationPluginsBootStrapper bootstrapper;

public void start() {
    bootstrapper.start();
}

四、文档内容定制

4.1 使用属性文件定义描述

Springfox支持从属性文件中解析描述文本，使文档内容可配置化：

@ApiOperation(value = "${controller.operation.value}")
@RequestMapping("/example")
public void exampleMethod(
    @ApiParam(value = "${controller.operation.param}") 
    @RequestParam String param) {
    // 方法实现
}

对应的属性文件：

controller.operation.value=示例操作描述
controller.operation.param=示例参数描述

4.2 覆盖属性数据类型

可以通过@ApiModelProperty注解覆盖属性的推断类型：

@ApiModelProperty(dataType = "com.example.CustomType")
public OriginalType getProperty() {
    return property;
}

4.3 操作ID(operationId)定制

Swagger 2.0规范中的operationId用于客户端代码生成，默认格式为"方法名UsingHTTP方法"：

@ApiOperation(value = "", nickname = "customOperationId")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getAllPets() {
    // 方法实现
}

生成的operationId将为"customOperationId"而非默认的"getAllPetsUsingGET"。

五、不同配置方式

5.1 XML配置方式

<!-- 必需配置 -->
<mvc:annotation-driven/>
<context:annotation-config/>

<!-- 引入Swagger配置类 -->
<bean class="com.example.config.SwaggerConfig"/>

对应的Java配置类：

@Configuration
@EnableSwagger
public class SwaggerConfig {
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }
}

5.2 Java配置方式

@Configuration
@EnableWebMvc  // 非Spring Boot应用需要
@EnableSwagger2
@ComponentScan("com.example.controllers")
public class SwaggerConfig {
    
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
    }
}

六、安全配置概述

Springfox的安全配置包含三个关键部分：

1. API实际保护：通过Spring Security等机制实现
2. 安全方案描述：定义使用的认证方式(ApiKey、BasicAuth、OAuth2等)
3. 安全上下文：指定哪些API受哪些安全方案保护

典型的安全配置示例：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
        .securitySchemes(Arrays.asList(apiKey()))  // 定义安全方案
        .securityContexts(Arrays.asList(securityContext()));  // 定义安全上下文
}

private ApiKey apiKey() {
    return new ApiKey("apiKey", "Authorization", "header");
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
        .securityReferences(defaultAuth())
        .forPaths(PathSelectors.regex("/secure/.*"))
        .build();
}

通过以上配置，开发者可以全面掌握Springfox的各项功能，为Spring Boot/Spring MVC应用生成专业、规范的API文档。

springfox Automated JSON API documentation for API's built with Spring 项目地址: https://gitcode.com/gh_mirrors/sp/springfox