Springfox、Swagger 和 Springdoc
Springfox、Swagger 和 Springdoc 是用于在 Spring Boot 项目中生成 API 文档的工具，但它们之间有显著的区别和演进关系：
1. Swagger
简介
- Swagger 是一个开源项目，旨在为 RESTful APIs 提供交互式文档。
- 最早由 SmartBear 开发，后来演进为 OpenAPI 规范 的前身。
- Swagger 的核心组件包括：
- Swagger UI：提供交互式的 Web 界面，展示 API 端点并允许直接调用测试。
- Swagger Editor：编写和查看 OpenAPI 描述文件的工具。
- Swagger Codegen：基于 API 描述文件生成客户端和服务端代码。
与 Spring 的关系
- Swagger 本身不依赖 Spring，但通过扩展工具（如 Springfox）使其在 Spring 框架中得到使用。
2. Springfox
简介
- 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 模块改动影响。
- 与 Spring Boot 2.6.x 和更高版本存在兼容性问题，主要是因为 Springfox 使用的
何时使用
- 如果项目是基于 Spring Boot 2.5.x 或更早版本，并且已经使用了 Springfox，可以暂时保留。
- 对于新项目，不建议继续使用 Springfox。
3. Springdoc
简介
- 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> - 启用后，访问默认路径
http://localhost:8080/swagger-ui.html。
总结：它们的关系与选择
| 工具 | 关系 | 适用场景 | 当前建议 |
|---|---|---|---|
| Swagger | 基础规范和工具 | 原始工具，用于标准化 API 文档 | 用于 OpenAPI 标准支持 |
| Springfox | Swagger 的 Spring 集成实现 | 传统项目（Spring Boot 2.5.x） | 不再推荐，已过时 |
| Springdoc | 基于 OpenAPI 3 的现代化替代工具 | 新项目，支持最新的 Spring Boot | 强烈推荐 |
迁移建议：从 Springfox 到 Springdoc
如果你当前使用 Springfox，但需要升级 Spring Boot 或改进文档支持，可以迁移到 Springdoc：
-
替换依赖：
- 移除
springfox-swagger2和springfox-swagger-ui。 - 添加
springdoc-openapi-ui。
- 移除
-
注解适配：
- Springdoc 支持 OpenAPI 3 的注解，通常是标准的 JSR-303 和 Spring 注解。
- 替换
@ApiOperation为@Operation，替换@ApiModel为标准注解。
-
配置改动：
- Springdoc 几乎不需要额外配置，大部分文档生成会自动完成。
结论：对于新项目，推荐使用 Springdoc；对于维护中的老项目，可以逐步迁移到 Springdoc，以便享受最新功能和更好的兼容性。