Springfox、Swagger 和 Springdoc

news2024/11/29 6:44:04

Springfox、Swagger 和 Springdoc 是用于在 Spring Boot 项目中生成 API 文档的工具，但它们之间有显著的区别和演进关系：

Swagger 是一个开源项目，旨在为 RESTful APIs 提供交互式文档。
最早由 SmartBear 开发，后来演进为 OpenAPI 规范 的前身。
Swagger 的核心组件包括：
- Swagger UI：提供交互式的 Web 界面，展示 API 端点并允许直接调用测试。
- Swagger Editor：编写和查看 OpenAPI 描述文件的工具。
- Swagger Codegen：基于 API 描述文件生成客户端和服务端代码。

Springfox 是一个专门为 Spring Boot 集成 Swagger 的库。
核心功能：扫描 Spring 项目中的注解和配置，生成基于 Swagger 的 API 文档。
特点：
- 支持 Spring MVC 和 Spring WebFlux。
- 使用 @ApiOperation 和 @ApiModel 等注解来生成文档。
- 支持 Swagger 2 和部分 OpenAPI 3 特性。

停止活跃维护：Springfox 项目在 2021 年后维护频率大幅降低，社区对它的支持逐渐减少。
兼容性问题：
- 与 Spring Boot 2.6.x 和更高版本存在兼容性问题，主要是因为 Springfox 使用的 RequestMappingHandlerMapping 被 Spring Framework 的 Web 模块改动影响。

Springdoc 是一个现代化工具，基于 OpenAPI 3 规范设计，替代 Springfox。
提供与 Spring Boot 的无缝集成：
- 自动生成 OpenAPI 3 文档。
- 提供嵌入式的 Swagger UI（无需单独配置）。
- 兼容 Spring MVC 和 Spring WebFlux。

强大兼容性：
- 与 Spring Boot 2.x 和 3.x 完美兼容。
- 支持 Spring Framework 的最新功能，例如响应式流和新注解模型。
零配置：
- 大部分功能开箱即用，减少了复杂的注解和配置需求。
社区活跃：
- 相比 Springfox，Springdoc 项目更活跃，持续发布新版本，解决社区反馈。

添加 Maven 依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>最新版本</version>
</dependency>

如果你当前使用 Springfox，但需要升级 Spring Boot 或改进文档支持，可以迁移到 Springdoc：

替换依赖：
- 移除 springfox-swagger2 和 springfox-swagger-ui。
- 添加 springdoc-openapi-ui。
注解适配：
- Springdoc 支持 OpenAPI 3 的注解，通常是标准的 JSR-303 和 Spring 注解。
- 替换 @ApiOperation 为 @Operation，替换 @ApiModel 为标准注解。
配置改动：
- Springdoc 几乎不需要额外配置，大部分文档生成会自动完成。