相关内容	地址
Swagger官方文档	https://swagger.io/docs/specification/2-0/basic-structure/
Swagger常用注解	https://blog.csdn.net/weixin_42526326/article/details/119824857
Swagger系列——Swagger2配置	https://blog.csdn.net/weixin_42526326/article/details/119963866
Swagger系列——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扫描显示的是类名

持续更新中。。。。