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,以便享受最新功能和更好的兼容性。