Springfox-SpringMVC 项目 Swagger 集成配置详解

Springfox-SpringMVC 项目 Swagger 集成配置详解

springfox 项目地址: https://gitcode.com/gh_mirrors/spr/springfox

项目概述

Springfox-SpringMvc 是一个优秀的 Spring MVC 与 Swagger 集成框架，它能够自动为基于 Spring MVC 的 RESTful API 生成 Swagger 文档。本文将深入讲解该项目的核心配置方法，帮助开发者快速掌握其使用技巧。

基础配置

启用 Swagger 支持

根据不同的 Swagger 规范版本，需要使用不同的注解：

// 支持 Swagger 1.2 规范
@EnableSwagger

// 支持 Swagger 2.0 规范
@EnableSwagger2

Docket 配置详解

Docket 是 Springfox 中的核心配置类，用于定义 API 文档的生成规则。它采用建造者模式设计，提供了灵活的 API 选择机制。

@Bean
public Docket swaggerSpringMvcPlugin() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("business-api")  // API 分组名称
            .select()
               // 忽略带有 @CustomIgnore 注解的控制器
              .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.*"));
}

高级配置技巧

ObjectMapper 定制

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

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

端点路径定制

默认的 Swagger 文档端点路径可以通过属性文件覆盖：

| Swagger 版本 | 覆盖属性 | |--------------|---------------------------------| | 1.2 | springfox.documentation.swagger.v1.path | | 2.0 | springfox.documentation.swagger.v2.path |

启动配置

可以通过 springfox.documentation.auto-startup 属性控制扫描时机：

• true（默认）：Spring 上下文刷新时自动扫描
• false：需要手动调用 Lifecycle#start() 方法

文档内容定制

属性文件描述覆盖

支持通过属性文件替换注解中的描述内容：

@ApiModelProperty(value="${property1.description}")
private String property;

对应的属性文件：

property1.description=属性描述内容

数据类型覆盖

使用 @ApiModelProperty 的 dataType 属性可以覆盖推断的数据类型：

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

OperationId 定制

Swagger 2.0 中的 operationId 默认格式为 方法名UsingHTTP方法，可通过 @ApiOperation 的 nickname 属性覆盖：

@ApiOperation(value = "", nickname = "customOperationId")
@RequestMapping(value = "/pets", method = RequestMethod.GET)
public Model getPets() { ... }

配置方式

XML 配置方式

1. 添加必要的 XML 配置：

<mvc:annotation-driven/>
<context:annotation-config/>
<bean class="com.yourapp.configuration.MySwaggerConfig"/>

2. 创建配置类：

@Configuration
@EnableSwagger
public class MySwaggerConfig {
    @Bean
    public Docket customDocket(){
        return new Docket();
    }
}

Java 配置方式

@Configuration
@EnableWebMvc  // 非 Spring Boot 应用需要
@EnableSwagger2
@ComponentScan("com.myapp.controllers")
public class CustomJavaPluginConfig {
    @Bean
    public Docket customImplementation(){
        return new Docket()
                .apiInfo(apiInfo());
    }
}

安全配置

Springfox 支持 Swagger 规范定义的所有安全方案：

1. API 保护方案（BasicAuth、ApiKey、OAuth2）
2. 安全上下文（定义哪些 API 受哪些方案保护）

最佳实践

1. 生产环境建议关闭自动启动，手动控制文档生成时机
2. 合理使用分组功能，将不同业务域的 API 分开管理
3. 充分利用属性文件管理描述内容，便于维护和国际化
4. 为重要操作定制有意义的 operationId，方便客户端生成

通过本文的详细讲解，开发者应该能够全面掌握 Springfox-SpringMvc 项目的配置方法，为 RESTful API 生成专业、规范的 Swagger 文档。

springfox 项目地址: https://gitcode.com/gh_mirrors/spr/springfox