【本文内容】
-
OpenAPI vs Swagger：
-
OpenAPI是规范 -
Swagger是规范的实现之一。
-
-
Swagger vs Springfox：
-
Swagger致力于API相关的设计、构建、展示，包括支持OpenAPI，但还支持其它如AsyncAPI，Json Schema等等，模块众多，语言也不仅限于Java。 -
Springfox致力于Java Spring相关的文档维护，但目前对于Spring Boot高版本（比如2.7.0）的支持并不是很好。
-
-
springdoc-openapi
-->【推荐使用】- 是Spring官方推出的OpenAPI规范的实现之一，可与swagger ui集成。
1. OpenAPI vs Swagger
- OpenAPI：是规范
- Swagger：规范的实现之一
Open API Initiative (OAI)发布的OpenAPI 3.0.0规范：https://www.openapis.org/blog/2017/07/26/the-oai-announces-the-openapi-specification-3-0-0
在OpenAPI 3.0.0规范的GitHub：https://github.com/OAI/OpenAPI-Specification/blob/main/README.md下，可以看到：
- 目前最新的规范版本为3.1.0，具体看这里。
- 在详情页链接：implementations，列举了一些OpenAPI 3.0规范的实现，有各种语言的，如Go，Java，Node.js等等。
其中对于OpenAPI 3.0规范的实现，Java相关的有：
-
swagger-parser：
Swagger的一个独立项目，用Java语言来转换OpenAPI的定义。
GitHub地址：https://github.com/swagger-api/swagger-parser
其中：- 版本1.X支持OpenAPI 2.0，
- 版本2.1.0支持OpenAPI 3.1
swagger-models：
基于OpenAPI 3.0的java实现，在swagger-core项目中。
GitHub地址：https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-models
其中：
- Swagger Core 1.5.x支持OpenAPI 2.0
- Swagger Core 2.x支持OpenAPI 3.x
springdoc-openapi【推荐使用，Demo详见第3章】：
Spring官方的基于OpenAPI 3.0.0的实现，支持Spring Boot 1.0+ 和2.0+版本。同时也支持Swagger-ui。
如果Spring Boot版本是3.0+，需要使用springdoc-openapi v2.0版本。
GitHub地址：https://github.com/springdoc/springdoc-openapispring-openapi：
支持Java Spring，并支持Jackson相关的注解以及可以自定义拦截器。
GitHub地址：https://github.com/jrcodeza/spring-openapi
2. Swagger vs Springfox
2.1 Swagger
官网：https://swagger.io/
Swagger主要是服务REST APIs的设计、文档、测试，包括一系列的开源产品。截图来自官网：
Swagger Editor：
可以在浏览器中用YAML编辑OpenAPI的定义。GitHub：https://github.com/swagger-api/swagger-editorSwagger Coegen
一款代码生成器。GitHub：https://github.com/swagger-api/swagger-codegen-
Swagger UI
自动生成OpenAPI的定义，可以在浏览器上进行查看，GitHub：https://github.com/swagger-api/swagger-ui。这个模块也是很多开发用的比较多的模块：image.png
除了以上三个模块，Swagger还有很多很多其它子项目，如SwaggerHub插件，Swagger-JS, Swagger-Parser, Swagger-Node等等。由此可见，Swagger项目并不局限于Java语言，它的目标是更好的设计、管理API，包括OpenAPI规范, AsyncAPI规范, JSON相关的Schema等等。
2.2 SpringFox
GitHub：https://github.com/springfox/springfox
官方文档：http://springfox.github.io/springfox/docs/current/
Springfox是Java的类库，可以自动为Spring框架生成JSON APIs的文档，并支持swagger, RAML, jsonapi等。主要的目标提为了更好的支持Spring相关的技术（包含Spring MVC）。
Hello World例子参考：https://www.baeldung.com/swagger-2-documentation-for-spring-rest-api
2.2.1 引入依赖
注：目前springfox对于Spring Boot的版本支持比较落后，比如3.0.0版本是他们唯一的release版本，能支持Spring Boot 2.2及以上版本。对于2.2以下的版本，不能使用springfox-boot-starter，而是需要手动引入springfox-swagger2以及springfox-swagger-ui。
但是springfox-boot-starter 3.0.0版本对于高版本的Spring Boot也并不能很好的支持，比如Spring Boot 2.7.0就不能和springfox-boot-starter兼容。
对于高版本的Spring Boot，推荐使用springdoc-openapi。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
本示例用的是Spring Boot 2.4.0版本。
2.2.2 加入配置
@Configuration
public class SpringFoxConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
【测试】
首先需要写一个UserController用来测试。
其次打开浏览器地址：http://localhost:8080/swagger-ui/
3. 推荐使用springdoc-openapi
在第1章OpenAPI的implementations第3个，即springdoc-openapi，就有介绍到springdoc-openapi是Spring官方推出的基于OpenAPI 3.0.0的实现。
Hello World例子参考：https://www.baeldung.com/spring-rest-openapi-documentation
3.1 引入依赖
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.4</version>
</dependency>
3.2 swagger-ui配置信息
默认swagger-ui的地址为/swagger-ui.html，也可在application.properties文件中修改，更多关于swagger-ui的配置，参考：https://springdoc.org/#swagger-ui-properties：
springdoc.swagger-ui.path=/swagger-ui-custom.html
默认情况下swagger-ui是开着的，也可通过配置进行关闭：springdoc.swagger-ui.enabled=false。
【测试】
和#2.2中的demo一样，需要写一个UserController用来测试。打开浏览器地址：http://localhost:8080/swagger-ui-custom.html
3.3 springdoc-openapi core配置信息
详细参考：https://springdoc.org/#properties
默认的路径为/v3/api-docs，可以修改：
springdoc.api-docs.path=/v3/api-docs/custom
默认spring-doc-openapi相关的信息也是开着的，可以通过修改配置进行关闭：springdoc.api-docs.enabled=false
【测试】
打开浏览器：http://localhost:8080/v3/api-docs/custom，如下：
