注解篇-Swagger常用注解详解

常用注解

@Api 标识一个java类型是文档类，用controller类的类名上

@ApiModel 表示一个实体类/模型文档，用在类名上；

@ApiModelProperty 作用在属性上，添加属性描述；

@ApiOperation 作用在接口类的方法上，控制方法的相关描述；

@ApiImplicitParam 作用在接口方法上，描述单个参数信息，只能作用在方法上；

@ApiImplicitParams 作用在接口方法上，@ApiImplicitParam参数组；

@ApiParam 作用在接口方法上，描述单个参数信息，属性基本与@ApiImplicitParam一样，但可以作用在方法、参数、属性上；

下面分别对每个注解的常用参数作讲解。

@Api：

value：字符串，对controller类的作用描述，代替原来的description（已过时），一般用此属性；

tags：字符串数组，标签组，同样可以描述controller的作用；

@ApiModel

value：字符串，模型的简短别名，使得在文档的导航中便于识别；

description：字符串，模型的附加描述；

@ApiOperation

value：字符串，方法的功能描述；

tags：字符串数组，标签组，同样可以描述方法的作用；

response：ClassType，显示指出返回的对象类型；在响应示例中会显示出改对象的字段以及示例、描述；

code：响应代码，默认200，一般不改；

@ApiModelProperty

value：字符串，字段描述；

required：boolean；指定参数是否必须，默认false；

example：字符串，参数值的示例

@ApiImplicitParam

name：字符串，参数名；

value：字符串，参数描述；

defaultValue：字符串，参数默认值；

required：boolean，标识是否必须传值，默认false；

dataType：字符串，参数类型，可以是某个类名，也可以是基本数据类型的引用类名，如Integer；

example：字符串，参数值示例；

@ApiImplicitParams

value：@ApiImplicitParam类型数组，当方法有多个@ApiImplicitParam参数时，需要放到@ApiImplicitParams注解中

@ApiParam

name：字符串，参数名；

value：字符串，参数描述；

defaultValue：字符串，设置默认值；

required：boolean，是否必须，默认false；

example：字符串，参数值示例；