Swagger3 相关总结

一、背景

1.1 OpenAPI 是啥？

OpenaAPI 是一个「API文档标准」，目前由 swagger 来维护，由于被 Linux 列为 API标准，从而成为行业标准。

1.2 Swagger 是啥？

swagger 是一个 API 文档维护组织，目前作为 OpenAPI 标准的主要定义者，现在最新的版本为17年发布的 Swagger3（OpenApi3）。

1.3 SpringFox 与 SpringDoc

SpringFox、SpringDoc 都是 spring 社区维护的项目（非官方），不同是：

1. SpringFox 帮助使用者将 swagger2 集成到 Spring 中。截至2020年4月，都未支持 OpenAPI3 标准。
2. SpringDoc 帮助使用者将 swagger3 集成到 Spring 中。

若想从之前使用的 SpringFox 迁移到 SpringDoc，步骤如下：

1. 从 pom.xml 里去掉 springfox 或者 swagger 的依赖

2. 添加 springdoc-openapi-ui 依赖，如下：

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

二 Swagger2 和 Swagger3 相关注解的对应关系

我和大多数人一样都是从 Swagger2 升级到 Swagger3。个人觉得为便于理解 Swagger3，从 Swagger2 和 Swagger3 的注解相互之间的对应关系开始说起比较好，如下图：

三、使用中的经验总结

上图罗列出来的注解基本上能涵盖工作中出现的大多数情况了。下面说几个我在工作当中碰到一些其他情况：

1. 返回的响应体包含自定义的 code，如果需要定义多个不同的 code 来对应不同的返回场景则使用 @ApiResponses，如果只会返回一个 code（即只有一个返回场景） 则使用 @ApiResponse，如下：

   • 定义多个不同的 code 来对应不同的返回场景

   @ApiResponses(value = {
       @ApiResponse(responseCode = "000000", description = "成功", useReturnTypeSchema = true),
       @ApiResponse(responseCode = "000001", description = "登录名或登录密码错误", content = { @Content(mediaType = "application/json", schema = @Schema())}),
       @ApiResponse(responseCode = "000002", description = "用户不存在", content = { @Content(mediaType = "application/json", schema = @Schema())})
   })
   public LoginUser login(@RequestParam(value = "loginName", ) String loginName, @RequestParam(value = "password") String password) {
   	...
   }
   

   • 只返回 1 个 code（即只有一个返回场景）

   @ApiResponse(responseCode = "000000", description = "成功", useReturnTypeSchema = true)
   public LoginUser login(@RequestParam(value = "loginName", ) String loginName, @RequestParam(value = "password") String password) {
   	...
   }
   

2. 如果 Controller 中的方法返回值是一个 List < UserDto >，这里的 UserDto 为自定义的类，则需要在 @ApiResponse 中的 content 中使用 array = @ArraySchema(…)，如下：

   @ApiResponse(responseCode = "000000", description = "成功", content = { @Content(mediaType = "application/json", array = @ArraySchema(schema = @Schema(implementation = UserDto.class)))})
   public List<AppDto> findUserList(@RequestParam(value = "codes") List codes) {
   	...
   }
   

3. 如果 Controller 中的方法返回值是一个自定义类，例如：UserDto，我们可以采用以下两种方式：

   • 复杂点儿的，采用 @ApiResponse 中的 content，如下：

   @ApiResponse(responseCode = "000000", description = "成功", content = { @Content(mediaType = "application/json", schema = @Schema(implementation = LoginUser.class))})
   public LoginUser login(@RequestParam(value = "loginName", ) String loginName, @RequestParam(value = "password") String password) {
   	...
   }
   

   • 简单点儿的 （个人推荐），采用 @ApiResponse 中的 useReturnTypeSchema，如下：

   @ApiResponse(responseCode = "000000", description = "成功", useReturnTypeSchema = true)
   public LoginUser login(@RequestParam(value = "loginName", ) String loginName, @RequestParam(value = "password") String password) {
   	...
   }
   

   通过上边的介绍，我们可以知道使用 useReturnTypeSchema 可以简化上边【2】中提到的返回 List< UserDto > 的场景，如下：

   @ApiResponse(responseCode = "000000", description = "成功", useReturnTypeSchema = true)
   public List<AppDto> findUserList(@RequestParam(value = "codes") List codes) {
   	...
   }