注解篇——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：字符串，参数值示例；

20201215追更 对@ApiModelProperty作进一步强调

@ApiModelProperty 注解中的example属性配置
不能直接以 以下特殊字符开头：{、[
想要以上面的特殊字符开头，需要转义，以下列出几个正确与错误的写法：
正确示例：
285044
\[285044
\{285044
28[5044
28{5044
285044{

错误示例：
[285044
{285044

ps：小生觉得，这是因为swagger生成的文档是json格式的数据，而在json语法中又 [、{ 开头且包住的认为是数组、对象，而一个数组或者对象没有经过格式化就赋给一个本应接收字符串的属性，这样肯定无法解析且报错的，所以经过转义后就又可以正常使用。

暂且追更到这，小生对技术见解尚浅，望各位道友一起共勉！