swagger常用注解详解

注解	使用位置	作用
@Api	类	对类的说明常用参数
@ApiOperation	方法	说明方法的用途、作用
@ApiImplicitParams	方法	表示一组参数说明
@ApiImplicitParam	@ApiImplicitParams中	表示单独的请求参数
@ApiModel	响应类	表示一个返回响应数据的信息
@ApiModelProperty	属性	描述响应类的属性
@ApiResponses	方法	表示一组响应
@ApiResponse	@ApiResponses中	一般用于表达一个错误的响应信息

@Api

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

参数	类型	描述
tags	String[]	说明该类的作用，非空时将覆盖value的值
value	String	描述类的作用
produces	String	设置mime类型，例：“application/json, application/xml”，默认为空
authorizations	Authorization[]	获取授权列表，如果未设置，则返回一个空的授权值
hidden	boolean	默认为false，配置true将在文档中隐藏
protocols	String	设置特定协议：http，https，ws，wss

@Api(protocols = "http", tags = {"模型controller"})
public class MOdelController {}

@ApiOperation

说明：用在请求的方法上，说明方法的用途、作用。

参数	类型	描述
value	String	说明方法的用途，作用
notes	String	方法的备注说明
tags	String[]	操作标签，非空时将覆盖value的值
response	Class<?>	响应类型(即返回对象)
responseContainer	String	声明包装的响应容器(返回对象类型)。有效值为"List",“Set”,“Map”
responseReference	String	指定对响应类型的引用。将覆盖任何指定的response()类
httpMethod	String	指定HTTP方法，“GET”, “POST”等
code	int	响应的HTTP状态码。默认200
produces	String	设置 MIME 类型列表（output），例：“application/json, application/xml”，默认为空
consumes	String	设置 MIME 类型列表（input），例：“application/json, application/xml”，默认为空

@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}

@APIParam

说明：参数和字段上，一般用在请求体参数上，描述请求体信息

注解属性	类型	描述
name	String	参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	String	参数的简要说明
required	boolean	参数是否必须传，默认为 false （路径参数必填）
defaultValue	String	参数的默认值
allowableValues	String	限制参数的可接受值。1.以逗号分隔的列表 2.范围值 3.设置最小值/最大值
access	String	允许从API文档中过滤参数

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

@ApiImplicitParams

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

@ApiImplicitParam

注解属性	类型	描述
name	String	参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value	String	参数的说明、解释
required	boolean	参数是否必须传，默认为 false （路径参数必填）
paramType	String	参数的位置，header 请求参数的获取：`@RequestHeader`；query 请求参数的获取：`@RequestParam`；path（用于 restful 接口）–> 请求参数的获取：`@PathVariable`；body（不常用）；form（不常用）
dataType	String	参数类型，默认 String，其它值 dataType=“Integer”
defaultValue	String	参数的默认值

@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 中，一般用于表达一个错误的响应信息

注解属性	类型	描述
code	int	响应状态码
message	String	信息，例如 “请求参数没填好”
response	Class<?>	抛出异常的类

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

@ApiModel

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

注解属性	类型	描述
value	String	模型的备用名称
description	String	该类的详细说明

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

@ApiModelProperty

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

注解属性	类型	描述
value	String	属性简要描述
name	String	重写属性名称
dataType	Stirng	重写属性类型
required	boolean	参数是否必传，默认为 false
example	Stirng	属性示例

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

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

原文链接：https://blog.csdn.net/loli_kong/article/details/108103746