Swagger3 相关总结

发布时间:2024年01月16日

一、背景

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) {
    	...
    }	
    
    
文章来源:https://blog.csdn.net/yangchao1125/article/details/135620143
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。