swagger 注解
<p><strong>1.swagger 注解</strong></p>
<pre><code>@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
httpMethod="方法的请求方式：GET,POST,HEAD,PUT,DELETE,OPTIONS,PATCH"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认string
defaultValue：参数的默认值
allowMultiple:允许多个值，表示数组
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
</code></pre>
<p><strong>2.自定义注解</strong></p>
<pre><code>@ApiJsonObject:用在请求的方法上，主要应用JSONObject,Map,JSON字符串
@ApiJsonProperty：用在@ApiJsonObject注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
example: 请求示例
dataType：参数类型，默认string
paramType：参数放在哪个地方，现只支持“body”
@ApiReturnJson：用在请求的方法上，表示一组响应
@ApiReturnJsonPro:用在@ApiReturnJson，一般用于表达一个正确的响应信息
name：参数名
value：参数的汉字说明、解释
example: 请求示例
dataType：参数类型，默认String.class
allowMultiple:允许多个值，表示数组
belongTo: 表示子层的父层，默认""</code></pre>
<p><strong>3.示例</strong></p>
<p><strong>3.1 @Api</strong></p>
<ol>
<li>
<p>@Api是写在类上的。</p>
</li>
<li>
<p>在swagger配置中，添加过滤机制，只有添加过@Api的类才被扫描到。</p>
</li>
<li>
<p>@Api的属性只写一个，就是tags，表示的类的作用，类似标签的作用：同一标签的接口会统合在一起，一个类可以有多个标签。<strong>这里只写一个tags值，且唯一。</strong></p>
</li>
<li>示例：</li>
</ol>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/0ee8fc257a292901f844fbd8330d4a9e?showdoc=.jpg" alt="" /></p>
<p>显示如下：</p>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/5ce7fc6c35a3e6955654ae1724cd092e?showdoc=.jpg" alt="" /></p>
<p><strong>3.2 @ApiOperation</strong></p>
<ol>
<li>
<p>@ApiOperation 添加到方法上的，说明有关接口的信息，具体如下。</p>
</li>
<li>
<p>@ApiOperation(value = "添加操作日志", notes = "添加操作日志", httpMethod = "POST")
value：表示接口的作用
notes: 对接口的具体描述
httpMethod: 表示接口的请求方式，有"GET,HEAD,POST,PUT,DELETE,OPTIONS,PATCH"</p>
<p><strong>注：</strong>因为没有指定请求方式，所以在页面上会显示所有请求方式的接口，即一个接口有7个接口文档。所以需要httpMethod来写明接口的请求方式。</p>
</li>
<li>示例</li>
</ol>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/2ad8b801ede3e51fd7b22de8c10a9334?showdoc=.jpg" alt="" /></p>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/6d1a118de0d7833a13122af63d5fc758?showdoc=.jpg" alt="" /></p>
<p>3.3 @ApiImplicitParams和@ApiImplicitParam</p>
<ol>
<li>
<p>@ApiImplicitParam 用来表示接口的请求参数</p>
</li>
<li>@ApiImplicitParam的示例</li>
</ol>
<pre><code>@ApiImplicitParams({
@ApiImplicitParam(name = "agencyId", dataType = "string", paramType = "query", required = true, value = "项目Id", example = "2b17255f4b2843ff801485de1126660f")
})
//name:参数名
//dataType:参数类型
//paramType:请求类型
//required:是否请求
//example: 示例</code></pre>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitfile/sign/464d861bdf36ba23de3bbf1b2ae29d63?showdoc=.jpg" alt="" /></p>