Springboot整合SpringDoc

swagger2与SpringDoc的区别与联系

主要区别

1、技术栈支持

1、Swagger2（springfox-swagger2）主要支持Spring MVC，对Spring Boot 2.x支持较好，但对Spring Boot 3.x和Spring 6支持有限

2、SpringDoc原生支持Spring Boot 2.x和3.x，完全兼容Spring WebFlux（响应式编程）

2、维护状态

1、Swagger2的springfox项目更新较慢，近年来维护不够活跃

2、SpringDoc是较新的项目，维护更积极，功能更完善。

3、配置方式

1、Swagger2需要较多手动配置，如创建Docket Bean

2、SpringDoc配置更简单，很多功能开箱即用，主要通过application.yml配置。

4、注解差异

1、Swagger2使用@Api、@ApiOperation等注解

2、SpringDoc使用OpenAPI 3规范的@Operation、@Tag等注解

联系

两者本质上都是为了实现同一个目标：根据代码自动生成API文档。SpringDoc可以看作是Swagger2的现代化替代方案，它：

1、遵循OpenAPI 3.0规范（Swagger2基于OpenAPI 2.0）

2、提供更好的Spring生态集成

3、支持更多现代Spring特性

迁移建议

如果你正在使用Spring Boot 2.6+或Spring Boot 3.x，建议迁移到SpringDoc，因为它提供更好的兼容性和更丰富的功能。对于老项目，Swagger2仍然可以继续使用，但长期来看SpringDoc是更好的选择。

优势

1、完美兼容: 原生支持Spring Boot 2.6+

2、活跃维护: 项目维护活跃，更新及时

3、OpenAPI 3.0: 支持最新的OpenAPI 3.0规范

4、零配置: 开箱即用，无需复杂配置

整合思路

1、添加Maven依赖

2、配置OpenAPI

创建OpenAPI配置类

编写配置文件

在application.yml中添加SpringDoc配置：

3、编写实体类

使用Schema注解

4、统一响应结果类

5、编写控制器类

6、访问和测试

访问

启动应用后，可以通过以下地址访问：

Swagger UI: http://localhost:8080/swagger-ui/index.html

API文档JSON:
http://localhost:8080/v3/api-docs

API文档YAML:
http://localhost:8080/v3/api-docs.yaml

测试

1、选择要测试的接口

2、填写必要参数

3、点击"Try it out"执行请求

4、查看响应结果