Swagger2常用注解说明

末蓝、 2021-09-21 09:34 507阅读 0赞

### 文章目录 ###

*   *  Swagger2简介
     *  使用Swagger解决的问题
     *  Spring Boot集成Swagger2
     *   *  添加依赖
         *  添加Swagger2Config配置类
         *  编写接口
         *   *  用户DTO
             *  用户controller
         *  访问接口文档
     *  Swagger2常用注解说明
     *   *  Controller相关注解
         *   *  @Api
         *  接口相关注解
         *   *  @ApiOperation
             *  @ApiParam
             *  @ApiImplicitParams
             *  @ApiImplicitParam
             *  @ApiResponses
             *  @ApiResponse
         *  Model相关注解
         *   *  @ApiModel
             *  @ApiModelProperty

## Swagger2简介 ##

[swagger官网][swagger] 对 swagger 的描述如下：

> Swagger takes the manual work out of API documentation, with a range of solutions for generating, visualizing, and maintaining API docs.
> 
> Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.

Swagger提供了用于生成，可视化和维护API文档的一系列解决方案，从而使API文档不再需要人工操作。

借助Swagger开源和专业工具集，为用户，团队和企业简化API开发。

**我的总结**：Swagger 是一套基于 OpenAPI 规范构建的开源工具，可以帮助我们设计、构建、使用和测试 Rest API。

## 使用Swagger解决的问题 ##

现在大部分公司都采用前后端分离开发的模式，前端和后端工程师各司其职。这就要求有一份及时更新且完整的Rest API 文档来提高工作效率。Swagger 解决的问题主要有以下三点：

1.  保证文档的时效性：只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，代码变文档跟着变
2.  接口请求参数和返回结果不明确的问题
3.  在线测试接口

## Spring Boot集成Swagger2 ##

这里通过构建一个简单的Spring Boot项目，并使用Swagger注解，来演示如何使用Swagger

### 添加依赖 ###

这里没有添加springfox-swagger2和springfox-swagger2-ui依赖，而是使用knife4j-spring-boot-starter依赖，官网地址：[https://doc.xiaominfo.com/knife4j/][https_doc.xiaominfo.com_knife4j]

<dependency>
        <groupId>javax.validation</groupId>
        <artifactId>validation-api</artifactId>
        <version>2.0.1.Final</version>
    </dependency>
    
    
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-boot-starter</artifactId>
        <version>2.0.3</version>
    </dependency>
    
    
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
    
    
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

### 添加Swagger2Config配置类 ###

注意：`RequestHandlerSelectors.basePackage("com.jourwon.springboot.knife4j.controller")` 为 Controller 包路径，不然生成的文档扫描不到接口，也可以使用`RequestHandlerSelectors.any()`配置

/** * Swagger2配置类 * * @author JourWon * @date 2020/6/1 */
    @EnableKnife4j
    @EnableSwagger2
    @Configuration
    @Import(value = { BeanValidatorPluginsConfiguration.class})
    public class Swagger2Config { 
    
        @Bean
        public Docket createRestApi() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.any())
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    // 标题
                    .title("我的Swagger API文档")
                    // 描述
                    .description("使用Knife4j构建API文档")
                    // 作者信息
                    .contact(new Contact("ThinkWon", "https://thinkwon.blog.csdn.net/", "thinkwon@163.com"))
                    // 服务网址
                    .termsOfServiceUrl("https://thinkwon.blog.csdn.net/")
                    // 版本
                    .version("1.0.0")
                    .build();
        }
    
    }

### 编写接口 ###

#### 用户DTO ####

/** * 用户 * * @author JourWon * @date 2020/6/1 */
    @Data
    @NoArgsConstructor
    @AllArgsConstructor
    @ApiModel(value = "用户", description = "查询用户")
    public class UserDTO implements Serializable { 
    
        private static final long serialVersionUID = 78806598597025327L;
    
        @ApiModelProperty(value = "用户id")
        private Integer userId;
    
        @ApiModelProperty(value = "用户名")
        private String username;
    
    }

#### 用户controller ####

/** * 用户controller * * @author JourWon * @date 2020/6/1 */
    @RestController
    @RequestMapping(value = { "/user"})
    @Api(tags = { "用户controller"})
    public class UserController { 
    
        private List<UserDTO> list = new ArrayList<>();
    
        @PostConstruct
        private void post() { 
            list.add(new UserDTO(1, "JourWon"));
            list.add(new UserDTO(2, "Jobs"));
            list.add(new UserDTO(3, "JackMa"));
        }
    
        @GetMapping("/list")
        @ApiOperation(value = "查询用户列表")
        public List<UserDTO> list() { 
            return list;
        }
    
        @GetMapping("/page")
        @ApiOperation(value = "分页查询用户列表")
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "pageNum", value = "当前页数"),
                @ApiImplicitParam(name = "pageSize", value = "每页记录数")
        })
        public List<UserDTO> page(
                @RequestParam(defaultValue = "1", required = false) Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) { 
            return list;
        }
    
        @GetMapping("/{userId}")
        @ApiOperation(value = "根据用户id查询用户")
        public UserDTO get(@PathVariable("userId") Integer userId) { 
            for (UserDTO userDTO : list) { 
                if (userDTO.getUserId().equals(userId)) { 
                    return userDTO;
                }
            }
            return new UserDTO();
        }
    
        @PostMapping
        @ApiOperation(value = "新增用户")
        public Boolean insert(@RequestBody @ApiParam(name = "UserDTO", value = "新增用户参数") UserDTO userDTO) { 
            list.add(userDTO);
            return true;
        }
    
        @DeleteMapping("/{userId}")
        @ApiOperation(value = "根据用户id删除用户")
        public Boolean delete(@PathVariable("userId") Integer userId) { 
            Iterator<UserDTO> iterator = list.iterator();
            while (iterator.hasNext()) { 
                if (iterator.next().getUserId().equals(userId)) { 
                    iterator.remove();
                    return true;
                }
            }
            return false;
        }
    
        @PutMapping
        @ApiOperation(value = "更新用户信息")
        @ApiResponses({ 
                @ApiResponse(code = 400, message = "请求参数没填好"),
                @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
        })
        public Boolean update(@RequestBody @ApiParam(name = "UserDTO", value = "更新用户参数") UserDTO userDTO) { 
            Iterator<UserDTO> iterator = list.iterator();
            while (iterator.hasNext()) { 
                UserDTO next = iterator.next();
                if (next.getUserId().equals(userDTO.getUserId())) { 
                    next.setUsername(userDTO.getUsername());
                    return true;
                }
            }
            return false;
        }
    
    }

这个controller有了六个接口，分别是:

1.  /user/list，get请求方式：查询用户列表
2.  /user/page，get请求方式：分页查询用户列表
3.  /user/\{userId\}，get请求方式：根据用户id查询用户
4.  /user，post请求方式：新增用户
5.  /user，put请求方式：更新用户信息
6.  /user/\{userId\}，delete请求方式：根据用户id删除用户

### 访问接口文档 ###

启动一下项目，然后在浏览器中访问 [http://localhost:8080/doc.html][http_localhost_8080_doc.html]

主页展示API文档基本信息，包括简介，作者，版本等信息

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center]

同时可以看到用户controller的所有接口

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center 1]

这里我们调试以下查询用户列表的接口

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center 2]

至此，Spring Boot集成Swagger2，构建API文档已经完成

## Swagger2常用注解说明 ##

### Controller相关注解 ###

#### @Api ####

用在请求的类上，表示对类的说明

示例

@Api(tags = { "用户controller"})
    public class UserController { }

### 接口相关注解 ###

#### @ApiOperation ####

用在请求类的方法上，说明方法的用途和作用

<table> 
 <thead> 
  <tr> 
   <th align="left"><strong>注解属性</strong></th> 
   <th align="left"><strong>类型</strong></th> 
   <th align="left"><strong>描述</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>value</strong></td> 
   <td align="left">String</td> 
   <td align="left">方法的简要说明</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>notes</strong></td> 
   <td align="left">String</td> 
   <td align="left">方法的备注说明</td> 
  </tr> 
  <tr> 
   <td align="left">非常用参数</td> 
   <td align="left"></td> 
   <td align="left"></td> 
  </tr> 
  <tr> 
   <td align="left">tags</td> 
   <td align="left">String[]</td> 
   <td align="left">操作标签，非空时将覆盖value的值</td> 
  </tr> 
  <tr> 
   <td align="left">response</td> 
   <td align="left">Class&lt;?&gt;</td> 
   <td align="left">响应类型（即返回对象）</td> 
  </tr> 
  <tr> 
   <td align="left">responseContainer</td> 
   <td align="left">String</td> 
   <td align="left">声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map”</td> 
  </tr> 
  <tr> 
   <td align="left">responseReference</td> 
   <td align="left">String</td> 
   <td align="left">指定对响应类型的引用。将覆盖任何指定的response()类</td> 
  </tr> 
  <tr> 
   <td align="left">httpMethod</td> 
   <td align="left">String</td> 
   <td align="left">指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”</td> 
  </tr> 
  <tr> 
   <td align="left">position</td> 
   <td align="left">int</td> 
   <td align="left">如果配置多个 Api 想改变显示的顺序位置，在 1.5 版本后不再支持</td> 
  </tr> 
  <tr> 
   <td align="left">nickname</td> 
   <td align="left">String</td> 
   <td align="left">第三方工具唯一标识，默认为空</td> 
  </tr> 
  <tr> 
   <td align="left">responseHeaders</td> 
   <td align="left">ResponseHeader[]</td> 
   <td align="left">响应头列表</td> 
  </tr> 
  <tr> 
   <td align="left">code</td> 
   <td align="left">int</td> 
   <td align="left">响应的HTTP状态代码。默认 200</td> 
  </tr> 
  <tr> 
   <td align="left">extensions</td> 
   <td align="left">Extension[]</td> 
   <td align="left">扩展属性列表数组</td> 
  </tr> 
  <tr> 
   <td align="left">produces</td> 
   <td align="left">String</td> 
   <td align="left">设置 MIME 类型列表（output），例：“application/json, application/xml”，默认为空</td> 
  </tr> 
  <tr> 
   <td align="left">consumes</td> 
   <td align="left">String</td> 
   <td align="left">设置 MIME 类型列表（input），例：“application/json, application/xml”，默认为空</td> 
  </tr> 
  <tr> 
   <td align="left">protocols</td> 
   <td align="left">String</td> 
   <td align="left">设置特定协议，例：http， https， ws， wss</td> 
  </tr> 
  <tr> 
   <td align="left">authorizations</td> 
   <td align="left">Authorization[]</td> 
   <td align="left">获取授权列表（安全声明），如果未设置，则返回一个空的授权值</td> 
  </tr> 
  <tr> 
   <td align="left">hidden</td> 
   <td align="left">boolean</td> 
   <td align="left">默认为 false，配置为 true 将在文档中隐藏</td> 
  </tr> 
 </tbody> 
</table>

示例

@GetMapping("/list")
    @ApiOperation(value = "查询用户列表")
    public List<UserDTO> list() { 
        return list;
    }

#### @ApiParam ####

可用在方法，参数和字段上，一般用在请求体参数上，描述请求体信息

@PostMapping
    @ApiOperation(value = "新增用户")
    public Boolean insert(@RequestBody @ApiParam(name = "UserDTO", value = "新增用户参数") UserDTO userDTO) { 
        list.add(userDTO);
        return true;
    }

#### @ApiImplicitParams ####

用在请求的方法上，表示一组参数说明，里面是`@ApiImplicitParam`列表

#### @ApiImplicitParam ####

用在 `@ApiImplicitParams` 注解中，一个请求参数的说明

<table> 
 <thead> 
  <tr> 
   <th align="left"><strong>注解属性</strong></th> 
   <th align="left"><strong>类型</strong></th> 
   <th align="left"><strong>描述</strong></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>name</strong></td> 
   <td align="left">String</td> 
   <td align="left">参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>value</strong></td> 
   <td align="left">String</td> 
   <td align="left">参数的说明、解释</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>required</strong></td> 
   <td align="left">boolean</td> 
   <td align="left">参数是否必须传，默认为 false （路径参数必填）</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>paramType</strong></td> 
   <td align="left">String</td> 
   <td align="left">参数的位置，header 请求参数的获取：<code>@RequestHeader</code>；query 请求参数的获取：<code>@RequestParam</code>；path（用于 restful 接口）–&gt; 请求参数的获取：<code>@PathVariable</code>；body（不常用）；form（不常用）</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>dataType</strong></td> 
   <td align="left">String</td> 
   <td align="left">参数类型，默认 String，其它值 dataType=“Integer”</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>defaultValue</strong></td> 
   <td align="left">String</td> 
   <td align="left">参数的默认值</td> 
  </tr> 
  <tr> 
   <td align="left">非常用参数</td> 
   <td align="left"></td> 
   <td align="left"></td> 
  </tr> 
  <tr> 
   <td align="left">allowableValues</td> 
   <td align="left">String</td> 
   <td align="left">限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值</td> 
  </tr> 
  <tr> 
   <td align="left">access</td> 
   <td align="left">String</td> 
   <td align="left">允许从API文档中过滤参数</td> 
  </tr> 
  <tr> 
   <td align="left">allowMultiple</td> 
   <td align="left">boolean</td> 
   <td align="left">指定参数是否可以通过具有多个事件接受多个值，默认为 false</td> 
  </tr> 
  <tr> 
   <td align="left">example</td> 
   <td align="left">String</td> 
   <td align="left">单个示例</td> 
  </tr> 
  <tr> 
   <td align="left">examples</td> 
   <td align="left">Example</td> 
   <td align="left">参数示例。仅适用于 BodyParameters</td> 
  </tr> 
 </tbody> 
</table>

@GetMapping("/page")
    @ApiOperation(value = "分页查询问题列表")
    @ApiImplicitParams({ 
        @ApiImplicitParam(name = "pageNum", value = "当前页数"),
        @ApiImplicitParam(name = "pageSize", value = "每页记录数")
    })
    public List<UserDTO> page(
        @RequestParam(defaultValue = "1", required = false) Integer pageNum, @RequestParam(defaultValue = "10", required = false) Integer pageSize) { 
        return list;
    }

#### @ApiResponses ####

用在请求的方法上，表示一组响应

#### @ApiResponse ####

用在 `@ApiResponses` 中，一般用于表达一个错误的响应信息

示例

@PutMapping
    @ApiOperation(value = "更新用户信息")
    @ApiResponses({ 
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    public Boolean update(@RequestBody @ApiParam(name = "UserDTO", value = "更新用户参数") UserDTO userDTO) { }

### Model相关注解 ###

#### @ApiModel ####

用在实体类（模型）上，表示相关实体的描述。

示例

@ApiModel(value = "用户", description = "查询用户")
    public class UserDTO implements Serializable

#### @ApiModelProperty ####

用在实体类属性上，表示属性的相关描述。

示例

@ApiModelProperty(value = "用户id")
    private Integer userId;
    
    @ApiModelProperty(value = "用户名")
    private String username;

[swagger]: https://swagger.io/
[https_doc.xiaominfo.com_knife4j]: https://doc.xiaominfo.com/knife4j/
[http_localhost_8080_doc.html]: http://localhost:8080/doc.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center]: /images/20210920/653868a7471e41bbae82575ec2d8ccb3.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20210920/cf66d426942d48859c12d31a97559f64.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L1RoaW5rV29u_size_16_color_FFFFFF_t_70_pic_center 2]: /images/20210920/3b2bd55887c54f6c98bf600ee3630339.png