Spring Boot整合Swagger教程详解,使用Springdoc-OpenAPI

什么是Swagger

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。它可以轻松的整合到现有的项目中，生成文档提供给前端开发人员来调用，还可以做功能测试。
在 Spring Boot 中，我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口，然后根据这些注解自动生成接口文档。

什么是Springdoc-openapi

SpringBoot官宣推出API工具
官网地址 https://springdoc.org/#getting-started
支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目

什么是openapi

OpenAPI Specification（OAS）定义了一个标准，用于描述REST API。它具有与Swagger 2.0规范兼容的根基础，但具有更强大的功能，例如支持JSON和YAML序列化，更好的安全性等。
[了解OpenAPI：什么是OpenAPI及其作用] https://zhuanlan.zhihu.com/p/624773325

Springdoc-openapi 与 Swagger的区别

Springdoc-openapi是SpringBoot官方推出的API工具，支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目。
Springdoc-openapi是基于OpenAPI 3规范构建的，而Swagger是基于OpenAPI 2规范构建的。

Springdoc-openapi 能代替 Swagger么
答案是可以的,但是Springdoc-openapi是基于OpenAPI 3规范构建的，而Swagger是基于OpenAPI 2规范构建的，所以在使用Springdoc-openapi时，需要注意一些细节，比如注解的变化等。

Springdoc-openapi的使用

引入依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

启动项目

访问 http://localhost:8080/swagger-ui.html

访问 http://localhost:8080/v3/api-docs 可以查看接口文档的json数据,该文档可以导出到支持OAS3.0的工具中,比如apifox

注意事项

注解

Springdoc-openapi中的注解与Swagger中的注解不同,细微之处可能有些调整

拦截器

如果有拦截器 注意查看是否拦截了swagger的请求

https://app.apifox.com/

可以使用apifox 导入swagger的json数据,然后进行接口测试,并且可以导出更友好的接口文档