OpenAPI 文档 (Swagger)

文章来源： http://ballcat.cn/guide/feature/openapi.html

什么是 OpenAPI

首先 OpenAPI 其实就是 Swagger, Swagger 规范于 2015 年 更名为 OpenAPI 规范，简称 OAS.

使用方式

由于 springfox 社区已经超过一年半的时间没有进行更新维护了，所以推荐大家使用 springdoc-openapi 来构建 swagger 文档。

springdoc 官方文档地址：https://springdoc.org，这里摘录并翻译部分，更多使用可参看原文档。

依赖引入

引入 ui 依赖后，在 springboot 环境下，直接启动即可，无需任何额外配置

• spring-webmvc 环境下引入

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>${lastedVersion}</version> 
</dependency>

• spring-webflux 环境下引入

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-webflux-ui</artifactId>
    <version>${lastedVersion}</version> 
 </dependency>

这将自动将 swagger-ui 部署到 spring-boot 应用程序：

• 文档将以 HTML 格式提供，使用官方 swagger-ui jars
• 启动项目后，访问 http://server:port/context-path/swagger-ui.html 即可进入 Swagger UI 页面，OpenAPI 描述将在以下 json 格式的 url 中 提供：http://server:port/context-path/v3/api-docs
• server：域名 或 IP
• port：服务器端口
• port：服务器端口
• 文档也可以 yaml 格式提供，位于以下路径：/v3/api-docs.yaml

替换 UI

如果嫌弃官方提供的 swagger-ui 不美观，或者使用不顺手，可以选择关闭 ui，还可以剔除掉 ui 相关的 webjar 的引入。

springdoc:
  swagger-ui:
    enabled: false

OpenAPI 文档信息，默认可在此 url 中获取：http://server:port/context-path/v3/api-docs。
可以利用其他支持 OpenAPI 协议的工具，通过此地址，进行 API 展示，如 Apifox。
（ Postman 的 api 测试也可以利用此地址进行导入生成 ）

Javadoc 支持

springdoc-openapi 目前支持将 javadoc 转换为 swagger 信息来源的能力，而无需用户在项目中添加对应的 Swagger 的注解。

对于想要启用 javadoc 支持的项目，在之前的依赖之外，还需要额外添加以下依赖：

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-javadoc</artifactId>
   <version>${lastedVersion}</version> 
</dependency>

此依赖项改进了对 javadoc 标记和注释的支持：

• 方法的 javadoc 注释：解析为 @Operation 描述
• @return : 解析为 @Operation 响应描述
• 属性的 javadoc 注释：被解析为此字段的 @Schema 描述。
  javadoc 支持基于 therapi-runtime-javadoc，所以需要开启了对应的注解处理器，否则不会生效
  在 maven-compiler-plugin 添加对应的注解处理器:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.github.therapi</groupId>
                        <artifactId>therapi-runtime-javadoc-scribe</artifactId>
                        <version>0.12.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>