Swagger常用注解及解释

1.请求类的描述

  

注解	说明
@Api	对请求类的描述

@Api：放在 请求的类上。与 @Controller 并列，说明类的作用，如用户模块，订单类等。

主要参数：

tags="说明该类的作用" 

全部参数：

属性名称	备注
value	url的路径值
tags	如果设置这个值、value的值会被覆盖
description	对api资源的描述
basePath	基本路径
position	如果配置多个Api 想改变显示的顺序位置
produces	如, “application/json, application/xml”
consumes	如, “application/json, application/xml”
protocols 协议类型	如: http, https, ws, wss.
authorizations	高级特性认证时配置
hidden	配置为true ，将在文档中隐藏

 

2. 方法和方法参数的描述

2.1 @ApiOperation：方法的说明

注解	说明
@ApiOperation	方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"

 

主要参数：

value="说明方法的作用"

notes="方法的备注说明"

 

2.2、@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParam：对单个参数的说明     

    name：参数名

    value：参数的说明、描述

    required：参数是否必须必填

    paramType：参数放在哪个地方

• query --> 请求参数的获取：@RequestParam
• header --> 请求参数的获取：@RequestHeader
• path（用于restful接口）--> 请求参数的获取：@PathVariable
• body（请求体）-->  @RequestBody User user
• form（普通表单提交）

    dataType：参数类型，默认String，其它值dataType="Integer"    

    defaultValue：参数的默认值

在单参数情况下可以只使用@ApiImplicitParam方法。

在同时有多个参数的情况下，需要结合@ApiImplicitParams、@ApiImplicitParam同时使用。

 

2. @ApiResponses、@ApiResponse：响应状态状态的说明

@ApiResponses：响应状态的说明。是个数组，可包含多个 @ApiResponse

@ApiResponse：每个参数的说明

    code：数字，例如400

    message：信息，例如"请求参数没填好"

    response：抛出异常的类

 

例如：

@ApiResponses({

@ApiResponse(code = 200, message = "请求成功"),

@ApiResponse(code = 400, message = "请求参数没填好"),

@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")

3. 对象的描述

4.1 @ApiModel：对象的整体说明

@ApiModel 经常用于请求的入参对象 和 响应返回值对象的描述。

1. 入参是对象，即@RequestBody 时， 用于封装请求（包括数据的各种校验）数据；
2. 返回值是对象，即@ResponseBody 时，用于返回值对象的描述。

@ApiModel(description = "用户登录")

public class UserLoginVO  implements  Serializable {

}

4.2 @ApiModelProperty 对象中每个参数的说明

@ApiModelProperty 用于每个属性上面，说明属生的含义。

例如

@ApiModel

public class UserLoginVO  implements  Serializable {

@ApiModelProperty(value = "用户名",required=true)

private String username;

}