【Spring Boot相关】关于OpenAPI，Swagger

【本文内容】

• 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相关的有：

1. swagger-parser：
   Swagger的一个独立项目，用Java语言来转换OpenAPI的定义。
   GitHub地址：https://github.com/swagger-api/swagger-parser
   其中：

   • 版本1.X支持OpenAPI 2.0，
   • 版本2.1.0支持OpenAPI 3.1

2. 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

3. 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-openapi

4. spring-openapi：
   支持Java Spring，并支持Jackson相关的注解以及可以自定义拦截器。
   GitHub地址：https://github.com/jrcodeza/spring-openapi

2. Swagger vs Springfox

2.1 Swagger

官网：https://swagger.io/
Swagger主要是服务REST APIs的设计、文档、测试，包括一系列的开源产品。截图来自官网：

image.png

• Swagger Editor：
  可以在浏览器中用YAML编辑OpenAPI的定义。GitHub：https://github.com/swagger-api/swagger-editor

• Swagger 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/

image.png

3. 推荐使用springdoc-openapi

在第1章OpenAPI的implementations第3个，即springdoc-openapi，就有介绍到springdoc-openapi是Spring官方推出的基于OpenAPI 3.0.0的实现。

• GitHub地址：https://github.com/springdoc/springdoc-openapi
• 官方文档：https://springdoc.org/

从官方示例来看，支持的case很多： image.png

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

image.png

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，如下：

image.png