Swagger常见注解@API、@ApiOperation、@ApiParam等

Posted 2023-03-09

参考技术A Swagger2一些常用注解

最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下

@API

使用在类上，表明是swagger资源，@API拥有两个属性:value、tags，源码如下

//If tags is not used,this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored.

String value() default "";

//Tags can be used for logical grouping of operations by resources or any other qualifier.

String[] tags() default "";

1

2

3

4

5

生成的api文档会根据tags分类，直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口

@Api(tags = "列表1")

@Api(tags = "列表1","列表2")

1

2

value的作用类似tags,但是不能有多个值

@ApiOperation

使用于在方法上，表示一个http请求的操作

源码中属性太多，记几个比较常用

value用于方法描述

notes用于提示内容

tags可以重新分组（视情况而用）

@ApiParam

使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等）

name–参数名

value–参数说明

required–是否必填

@ApiModel()

使用在类上，表示对类进行说明，用于参数用实体类接收

value–表示对象名

description–描述

@ApiModelProperty()

使用在方法，字段上，表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏