Swagger使用纪要

一、常用注解说明

1、@Api

@Api：用在请求的类上，表示对类的说明
    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"

2、@ApiOperation

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

3、@ApiImplicitParams

1）注解基础说明

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：参数类型，默认String，其它值dataType="Integer"       
        defaultValue：参数的默认值

2）@ApiImplicitParam属性dataType单独使用会出现的bug说明

• 问题描述

如果你的项目模块，swagger配置了分组，如下图

其效果

这时，swagger有一个非常坑的bug：你的注解@ApiImplicitParam属性dataType，不能单独使用，否则会引起一个前端错误、导致当前分组Api文档无法显示（页面会停留在点击前的页面、不跳转）。
bug截图

• 解决方式
  如果要设置分组，那么使用@ApiImplicitParam注解时，dataType属性要么不使用，要么就和paramType属性一起使用
  这个应该时swagger的一个bug，并没有逻辑性，我是通过一次一次测试得到的结果。（花了整整一天时机做这种没意义的事，希望大家不用重蹈覆辙~）
  下面把测试截图记录一下，当时已知name和value属性是干净的，dataType单独使用不行、必须和paramType组合使用：
  a、怀疑是dataType位置导致的，做以下测试，发现bug没有修复；
  
  b、又想是不是dataType和required属性组合也可以，做以下测试，bug没有修复
  
  b、经测试，配置分组后@ApiImplicitParam注解的dataType属性就只能和paramType属性一起使用，或者不使用；单独使用就会引发上述错误。与属性先后顺序（位置）无关。

3.5、@ApiImplicitParams常用配套参数@ApiIgnore和@ApiModelProperty属性hidden

1）痛点

使用@ApiImplicitParam注解备注参数后，文档会有这样的问题：就是注解的备注会显示，方法形参也会显示（名称相同就显示一个）。这样会导致api文档特别冗余，很难读、还容易引发歧义，而且与我们的初衷也不相符，我都用@ApiImplicitParam注解了，肯定是希望以注解的备注为准啊，形参的显示混淆了视听。

2）解决

这时我们肯定想，其实不是入参的字段在swagger文档中隐藏掉；可以用以下几种方法。（隐藏，是指不在swagger接口文档中显示）
a、使用@ApiIgnore注解（最简单实用）
该注解用在方法的形参列表，它会将其后的参数隐藏掉；如果注解后是一个实体类，那么该实体类的所有字段都会被隐藏。


b、使用@ApiModelProperty的hidden属性
如果你的接口参数是用实体类接收的，那么你可以在字段上使用@ApiModelProperty注解，并将其属性hidden值设为true，这样该字段就会在swagger文档上隐藏了。
但是这个方法有个问题，当实体类字段特别多时，那你就需要加非常多@ApiModelProperty注解才能把它们全部隐藏。
不过它也有适用场景，当你不用@ApiImplicitParam注解备注接口入参、就用@ApiModelProperty注解备注时，你就可以用hidden属性将实体类中不是入参的其他字段隐藏掉。

4、@ApiModel

@ApiModel：用于类，表示对类进行说明，用于参数用实体类接收 
	value：表示对象名 
	description：描述 

5、@ApiModelProperty

@ApiModelProperty：用于字段； 表示对model属性的说明或者数据操作更改 
	value：字段说明 
	name：重写属性名字（实测没什么用，seagger会自动强制写属性名） 
	dataType：重写属性类型 （也没什么用，seagger会自动强制写属性类型）
	required：是否必填，Boolean类型，默认flase（必填字段会有个*）
	example：举例说明（可以给一个字段值示例）
	hidden：是否隐藏，Boolean类型，默认flase

6、@ApiModel

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性