SpringFox项目从1.x升级到2.x的技术指南

SpringFox项目从1.x升级到2.x的技术指南

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

模块结构重构

SpringFox 2.0版本对原有的模块结构进行了重大调整。在1.x版本中，主要包含swagger-springmvc和swagger-models两个核心模块。而在2.0版本中，项目团队重新设计了整体架构，将其拆分为多个职责更加明确的模块。

架构设计理念

新版本采用了两阶段处理的设计思想：

1. 服务模型推断阶段：首先将API服务推断为内部表示模型
2. 规范映射阶段：然后将内部模型映射到不同的规范格式

这种设计不仅支持Swagger 1.2和2.0规范，还为未来支持RAML、ALPS等其它API描述格式提供了可能性。

新模块架构

以下是2.0版本的模块结构及其职责：

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

springfox-spi
└── 提供可扩展的服务提供接口，用于丰富服务模型

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 1.2规范：@EnableSwagger
• Swagger 2.0规范：@EnableSwagger2

核心配置类变更

1. 废弃的类：

   • SwaggerSpringMvcPlugin
   • SpringSwaggerConfig

2. 新的配置类：

   • Docket：取代了SwaggerSpringMvcPlugin，提供了更灵活、格式无关的API文档配置方式

Docket配置示例

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

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

实用谓词工具类

• RequestHandlerSelectors：提供多种请求处理器选择方式
• PathSelectors：提供多种路径匹配方式

高级配置技巧

ObjectMapper配置

推荐通过监听ObjectMapperConfigured事件来配置ObjectMapper，这样可以确保自定义配置应用到所有相关的ObjectMapper实例上。

实现方式：

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

自定义Swagger端点

默认端点：

• Swagger 1.2：/api-docs
• Swagger 2.0：/v2/api-docs

通过属性文件可自定义这些端点：

# Swagger 1.2端点自定义
springfox.documentation.swagger.v1.path=/custom-api-docs

# Swagger 2.0端点自定义
springfox.documentation.swagger.v2.path=/api/v2/docs

属性数据类型覆盖

使用@ApiModelProperty注解的dataType属性可以覆盖推断出的数据类型，但必须使用完全限定类名：

// 使用完全限定类名确保类型替换成功
@ApiModelProperty(dataType = "com.example.CustomType")
public OriginalType getProperty() { ... }

扩展性机制

SpringFox 2.0提供了多种扩展点，允许开发者自定义和增强API文档生成过程：

1. 模型和属性增强：可自定义模型和属性的表示方式
2. 服务模型增强：可扩展和修改API服务的描述信息

（注：具体扩展实现方式需参考项目文档中的详细示例）

升级建议

1. 逐步迁移：建议先在一个非关键服务上尝试升级
2. 测试验证：特别注意自定义配置和扩展点的兼容性
3. 利用谓词：新版本的路径选择机制更强大，可简化原有配置

通过以上调整，SpringFox 2.0提供了更清晰、更灵活的API文档生成方案，虽然升级需要一定的工作量，但新架构的扩展性和可维护性优势明显。

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