Swagger笔记之Swagger注解
@
目录
Swagger-注解：
| 作用范围 | API | 使用位置 |
|---|---|---|
| 协议集描述 | @Api | 用于controller类上 |
| 对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
| 协议描述 | @ApiOperation | 用在controller的方法上 |
| Response集 | @ApiResponses | 用在controller的方法上 |
| Response | @ApiResponse | 用在 @ApiResponses里边 |
| 非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
| 非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
| 校验绑定的参数 | @Valiated | 用在controller的方法上 |
| 描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
api标记，用在类上，说明该类的作用。可以标记一个Controller类做为Swagger文档资源，使用方式
与Controller注解并列使用。 属性配置：
Controller 控制器
@Api
tags 一定要写，不然swagger扫描显示的是类名
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, "application/json, application/xml" |
| consumes | For example, "application/json, application/xml" |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true 将在文档中隐藏 |
@ApiOperation
ApiOperation标记，用在方法上，说明方法的作用，每一个url资源的定义,使用方式：
@ApiOperation("获取用户信息")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| value | url的路径值 |
| tags | 如果设置这个值、value的值会被覆盖 |
| description | 对api资源的描述 |
| basePath | 基本路径可以不配置 |
| position | 如果配置多个Api 想改变显示的顺序位置 |
| produces | For example, "application/json, application/xml" |
| consumes | For example, "application/json, application/xml" |
| protocols | Possible values: http, https, ws, wss. |
| authorizations | 高级特性认证时配置 |
| hidden | 配置为true将在文档中隐藏 |
| response | 返回的对象 |
| responseContainer | 这些对象是有效的 "List", "Set" or "Map".，其他无效 |
| httpMethod | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" |
| code | http的状态码 默认 200 |
| extensions | 扩展属性 |
@ApiParam
ApiParam标记，请求属性，使用方式：
public TableDataInfo list(@ApiParam(value = "查询用户列表", required = true)User user)
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
@ApiResponse
ApiResponse标记，响应配置，使用方式：
@ApiResponse(code = 400, message = "查询用户失败")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| code | http的状态码 |
| message | 描述 |
| response | 默认响应类 Void |
| reference | 参考ApiOperation中配置 |
| responseHeaders | 参考 ResponseHeader 属性配置说明 |
| responseContainer | 参考ApiOperation中配置 |
@ApiResponses
ApiResponses标记，响应集配置，使用方式:
@ApiResponses({ @ApiResponse(code = 400, message = "无效的用户") })
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| value | 多个ApiResponse配置 |
@ResponseHeader
ResponseHeader标记，响应头设置，使用方法
@ResponseHeader(name="head",description="响应头设计")
与Controller中的方法并列使用，属性配置：
| 属性名称 | 备注 |
|---|---|
| name | 响应头名称 |
| description | 描述 |
| response | 默认响应类 void |
| responseContainer | 参考ApiOperation中配置 |
火中取栗
@RestController
@RequestMapping("/msg/im")
@Api(tags = "消息-IM")
public class IMController {
@ApiOperation("生成用户签名")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户ID", required = true, dataType = "String")
})
@GetMapping("/{userId}")
public R<String> test(@PathVariable("userId") @ApiParam(value = "用户ID", required = true) String userId) {
return R.ok(IMTencentUtil.genUserSig(userId));
}
}
VO 返回对象
其中@Null、@NotNull。。等与@Valiated 配合使用
| 限制 | 说明 |
|---|---|
| @Null | 限制只能为null |
| @NotNull | 限制必须不为null |
| @AssertFalse | 限制必须为false |
| @AssertTrue | 限制必须为true |
| @DecimalMax(value) | 限制必须为一个不大于指定值的数字 |
| @DecimalMin(value) | 限制必须为一个不小于指定值的数字 |
| @Digits(integer,fraction) | 限制必须为一个小数，且整数部分的位数不能超过integer，小数部分的位数不能超过fraction |
| @Future | 限制必须是一个将来的日期 |
| @Max(value) | 限制必须为一个不大于指定值的数字 |
| @Min(value) | 限制必须为一个不小于指定值的数字 |
| @Past | 限制必须是一个过去的日期 |
| @Pattern(value) | 限制必须符合指定的正则表达式 |
| @Size(max,min) | 限制字符长度必须在min到max之间 |
| @Past | 验证注解的元素值（日期类型）比当前时间早 |
| @NotEmpty | 验证注解的元素值不为null且不为空（字符串长度不为0、集合大小不为0） |
| @NotBlank | 验证注解的元素值不为空（不为null、去除首位空格后长度为0），不同于@NotEmpty，@NotBlank只应用于字符串且在比较时会去除字符串的空格 |
| 验证注解的元素值是Email，也可以通过正则表达式和flag指定自定义的email格式 |
@ApiModel
用在返回对象类上
| 属性名称 | 备注 |
|---|---|
| value | 默认 为模型提供一个替代名称 |
| description | 描述 |
| referencey | 指定对相应类型定义的引用，覆盖指定的任何其他元数据 |
@ApiModelProperty
用在返回对象的属性上
| 属性名称 | 备注 |
|---|---|
| value | 默认 字段说明 |
| name | 重写属性名字 |
| dataType | 重写属性类型 |
| required | 是否必填 |
| example | 举例说明 |
| hidden | 配置为true将在文档中隐藏 |
火中取栗
@ApiModel("testVo")
public class MsgPageVO
{
/** 消息ID */
@ApiModelProperty("消息ID")
private Long msgId;
}
注意：
@Api(tags = "")写，不然swagger扫描显示的是类名
持续更新中。。。。
