Swagger笔记之Swagger注解

@

目录

相关内容 地址
Swagger官方文档 https://swagger.io/docs/specification/2-0/basic-structure/
Swagger常用注解 https://blog.csdn.net/weixin_42526326/article/details/119824857
Swagger2常用注解 https://blog.csdn.net/weixin_42526326/article/details/119963866
Swagger3常用注解 https://blog.csdn.net/weixin_42526326/article/details/119965092

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 验证注解的元素值是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扫描显示的是类名

持续更新中。。。。

posted @ 2021-12-08 20:40  好奇新  阅读(1559)  评论(0)    收藏  举报