Swagger3 注解使用（Open API 3）

柔情只为你懂 2023-07-23 03:36 51阅读 0赞

# swagger 3 的使用 #

Swagger2（基于openApi3）已经在17年停止维护了，取而代之的是 sagger3（基于openApi3），而国内几乎没有 sagger3使用的文档，百度搜出来的都是swagger2的使用，这篇文章将介绍如何在 java 中使用 openApi3（swagger3）。

## 相关介绍 ##

#### Open API ####

OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

#### Swagger ####

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（Open Api3）。  
国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）  
**swagger2**的包名为 `io.swagger`，而**swagger3**的包名为 `io.swagger.core.v3`。

#### SpringFox ####

SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。  
常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。  
截至2020年4月，都未支持 OpenAPI3 标准。

> 补充：2020.7.14 发布了 3.0 支持 OpenAPI3，[github 发布记录][github] 但官网对 3.0 版本相关文档未完善，还是只有 swagger 2.0 相关的。  
> [升级到 OpenAPI3（java 中 swagger1.x 对应 OpenAPI2、swagger 2.x对应OpenAPI3）官方文档][OpenAPI3_java _ swagger1.x _ OpenAPI2_swagger 2.x_OpenAPI3]

3.0 相关特性

*  支持 `Spring 5`，`Webflux`（仅请求映射支持，尚不支持功能端点）、`Spring Integration`
 *  补充官方在 spring boot 的自动装配 `pringfox-boot-starter` 以后可以直接依赖一个 dependency
 *  与2.0更好的规范兼容性
 *  支持OpenApi 3.0.3
 *  轻依赖 [spring-plugin][]，[swagger-core][]
 *  现有的swagger2批注将继续有效并丰富开放式API 3.0规范

#### [SpringDoc][] ####

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。  
也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

该组织下的项目支持swagger页面Oauth2登录（Open API3的内容），相较 SpringFox来说，它的支撑时间更长，无疑是更好的选择。但由于国内发展较慢，在国内不容易看到太多有用的文档，不过可以访问它的[官网][SpringDoc]。它的使用了 swagger3（OpenAPI3），但 swagger3 并未对 swagger2 的注解做兼容，不易迁移，也因此，名气并不如 spring fox。

--------------------

## [从 spring-fox 迁移到 springdoc][spring-fox _ springdoc] ##

#### 依赖变更 ####

pom.xml 里去掉 springfox 或者 swagger 的依赖。添加`springdoc-openapi-ui`。

<dependency>
          <groupId>org.springdoc</groupId>
          <artifactId>springdoc-openapi-ui</artifactId>
          <version>1.3.1</version>
       </dependency>

#### 使用 swagger3 注解代替 swagger2 的（可选） ####

这一步是可选的，因为改动太大，故 springfox对旧版的 swagger做了兼容处理。  
但不知道未来会不会不兼容，这里列出如何用 swagger 3 的注解（已经在上面引入）代替 swagger 2 的  
(**注意**修改 swagger 3 注解的包路径为`io.swagger.v3.oas.annotations.`)

对应关系为：

<table> 
 <thead> 
  <tr> 
   <th align="left">swagger2</th> 
   <th align="left"><strong>OpenAPI 3</strong></th> 
   <th align="left">注解位置</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><code>@Api</code></td> 
   <td align="left"><strong>@Tag(name = “接口类描述”)</strong></td> 
   <td align="left">Controller 类上</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiOperation</code></td> 
   <td align="left"><strong>@Operation(summary =“接口方法描述”)</strong></td> 
   <td align="left">Controller 方法上</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiImplicitParams</code></td> 
   <td align="left"><strong>@Parameters</strong></td> 
   <td align="left">Controller 方法上</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiImplicitParam</code></td> 
   <td align="left"><strong>@Parameter(description=“参数描述”)</strong></td> 
   <td align="left">Controller 方法上 <code>@Parameters</code> 里</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiParam</code></td> 
   <td align="left"><strong>@Parameter(description=“参数描述”)</strong></td> 
   <td align="left">Controller 方法的参数上</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiIgnore</code></td> 
   <td align="left"><strong>@Parameter(hidden = true)</strong> 或 <strong>@Operation(hidden = true)</strong> 或 <strong>@Hidden</strong></td> 
   <td align="left">-</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiModel</code></td> 
   <td align="left"><strong>@Schema</strong></td> 
   <td align="left">DTO类上</td> 
  </tr> 
  <tr> 
   <td align="left"><code>@ApiModelProperty</code></td> 
   <td align="left"><strong>@Schema</strong></td> 
   <td align="left">DTO属性上</td> 
  </tr> 
 </tbody> 
</table>

Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。

#### 修改Api 分组（当且仅当你之前定义了多个 Docket Bean） ####

旧：

@Bean
        public Docket publicApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
                    .paths(PathSelectors.regex("/public.*"))
                    .build()
                    .groupName("springshop-public")
                    .apiInfo(apiInfo());
        }
      
        @Bean
        public Docket adminApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
                    .paths(PathSelectors.regex("/admin.*"))
                    .build()
                    .groupName("springshop-admin")
                    .apiInfo(apiInfo());
        }

新：

@Bean
        public GroupedOpenApi publicApi() { 
            return GroupedOpenApi.builder()
                    .setGroup("springshop-public")
                    .pathsToMatch("/public/**")
                    .build();
        }
      
        @Bean
        public GroupedOpenApi adminApi() { 
            return GroupedOpenApi.builder()
                    .setGroup("springshop-admin")
                    .pathsToMatch("/admin/**")
                    .build();
        }

如果之前只有一个 Docket，则把他删了，用配置文件替代它

springdoc.packagesToScan=package1, package2
    springdoc.pathsToMatch=/v1, /api/balance/**

## 其他情况 ##

#### swagger ui在代理的后面，如 nginx ####

参见这篇  
https://springdoc.org/faq.html\#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.

#### 自定义 Swagger UI ####

https://springdoc.org/faq.html\#how-can-i-configure-swagger-ui.

#### 在文档中隐藏某个接口或者 Controller ####

https://springdoc.org/faq.html\#how-can-i-hide-an-operation-or-a-controller-from-documentation-.

[github]: https://github.com/springfox/springfox/releases
[OpenAPI3_java _ swagger1.x _ OpenAPI2_swagger 2.x_OpenAPI3]: https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#quick-annotation-overview
[spring-plugin]: https://github.com/spring-projects/spring-plugin
[swagger-core]: https://github.com/swagger-api/swagger-core
[SpringDoc]: https://springdoc.org/
[spring-fox _ springdoc]: https://springdoc.org/migrating-from-springfox.html