Swagger-SpringMVC 项目从 V1 迁移到 V2 的完整指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00004/article/details/148488380

Swagger-SpringMVC 项目从 V1 迁移到 V2 的完整指南

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

模块架构的重大变化

在 Swagger-SpringMVC 项目从 V1 升级到 V2 的过程中，最显著的变化是整个架构被重新设计为更加模块化的结构。原先的两个主要模块 swagger-springmvc 和 swagger-models 现在被拆分成多个职责更加明确的模块。

新架构设计理念

项目团队在设计 V2 版本时，意识到需要重构服务模型和模式推断的逻辑。因此采用了两步走的策略：

服务模型推断：首先将服务模型推断为内部表示形式
映射层：然后创建映射层，将内部模型映射到不同的规范格式

这种设计带来了以下优势：

原生支持 Swagger 1.2 和 2.0 规范
未来可扩展支持其他格式如 RAML、ALPS 和超媒体格式
各模块职责更加清晰，便于维护和扩展

新模块结构详解

以下是新版本的核心模块及其功能：

springfox-core
└── 包含内部服务和模式描述模型及其构建器

springfox-spi
└── 包含服务提供者接口，可用于扩展和丰富服务模型
    └── 例如Swagger特定注解处理器

springfox-schema
└── 帮助构建参数、模型和响应的模式推断扩展

springfox-spring-web
└── 基于Spring Web的扩展，根据RequestMapping信息构建服务模型
    └── 这是推断服务模型的核心库

springfox-swagger-common
└── 通用的Swagger特定扩展，能识别不同的Swagger注解

springfox-swagger1
└── 配置和映射层，知道如何将服务模型转换为Swagger 1.2规范文档

springfox-swagger2
└── 配置和映射层，知道如何将服务模型转换为Swagger 2.0规范文档

配置变更详解

包名变更

所有包名从 com.mangofactory.swagger 变更为 springfox.documentation，这一变化反映了项目的发展和标准化进程。

启用Swagger支持

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

// 启用Swagger 1.2支持
@EnableSwagger

// 启用Swagger 2.0支持
@EnableSwagger2

核心配置类变更

不再使用 SwaggerSpringMvcPlugin 来配置文档子集，而是引入了更通用的 Docket 类。这一变化使得文档内容的表达与文档呈现格式解耦。

主要变化点：

不再需要 SpringSwaggerConfig 类来配置 Docket

移除了原有的自动装配代码：

@Autowired
private SpringSwaggerConfig swaggerConfig;

Docket 类详解

Docket 名称来源于法律术语，意为"文档内容摘要"。它与 SwaggerSpringMvcPlugin 类似，但提供了更强大的API选择能力。

典型配置示例：

@Bean
public Docket swaggerSpringMvcPlugin() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("business-api")
            .select() 
               // 忽略带有@CustomIgnore注解的控制器
              .apis(not(withClassAnnotation(CustomIgnore.class)) // 通过RequestHandler选择
              .paths(paths()) // 通过路径选择
              .build()
            .apiInfo(apiInfo())
            .securitySchemes(securitySchemes())
            .securityContext(securityContext());
}

// 路径选择谓词示例
private Predicate<String> paths() {
    return or(
        regex("/business.*"),
        regex("/some.*"),
        regex("/contacts.*"),
        regex("/pet.*"));
}

实用谓词工具：

RequestHandlerSelectors：提供多种基于请求处理器的选择方式
PathSelectors：提供多种基于路径的选择方式

高级配置技巧

配置ObjectMapper

推荐通过监听 ObjectMapperConfigured 事件来配置ObjectMapper。无论应用中是否存在自定义的ObjectMapper，库始终会配置一个专用于序列化Swagger 1.2和2.0类型的ObjectMapper。

实现方式：

@Component
public class ObjectMapperConfigurer implements ApplicationListener<ObjectMapperConfigured> {
    @Override
    public void onApplicationEvent(ObjectMapperConfigured event) {
        ObjectMapper objectMapper = event.getObjectMapper();
        // 在这里添加自定义配置
        objectMapper.setSerializationInclusion(Include.NON_NULL);
    }
}

注意：如果在应用启动时遇到NullPointerException，可能是因为缺少 @EnableWebMvc 注解。

自定义Swagger端点

默认的Swagger文档生成URL：

| Swagger版本 | 默认URL | |------------|-------------| | 1.2 | /api-docs | | 2.0 | /v2/api-docs |

可以通过属性文件覆盖这些端点：

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

覆盖属性数据类型

使用 @ApiModelProperty#dataType 可以覆盖推断的数据类型，但需要注意：

必须使用完全限定类名
如果指定的类无法通过 Class.forName() 加载，原始类型将被保留

示例：

// 成功替换的情况
@ApiModelProperty(dataType = "com.example.ReplacedWith")
public Original getOriginal() { ... }

// 替换失败的情况（保留Original类型）
@ApiModelProperty(dataType = "InvalidType")
public Original getAnotherOriginal() { ... }