系统接口
<h1><center>系统接口</center></h1>
<p>在现在的开发过程中还有很大一部分公司都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，或者写了代码再写文档。 还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了。 只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过Swagger，我们可以省略了这一步，而且文档出错率近乎于零， 只要你在写代码的时候，稍加几个注解，文档自动生成。</p>
<h3>1、在控制层Controller中添加注解来描述接口信息如:</h3>
<pre><code>@Api("参数配置")
@Controller
@RequestMapping("/system/config")
public class ConfigController</code></pre>
<h3>2、在方法中配置接口的标题信息</h3>
<p>ApiOperation标记，用在方法上，说明方法的作用，每一个url资源的定义,使用方式：</p>
<pre><code>@ApiOperation("查询参数列表")</code></pre>
<h3>3、在系统工具-系统接口测试相关接口</h3>
<hr />
<p>注意：SwaggerConfig可以指定根据注解或者包名扫描具体的API</p>
<h4>API详细说明</h4>
<table>
<thead>
<tr>
<th>作用范围</th>
<th>API</th>
<th>使用位置</th>
</tr>
</thead>
<tbody>
<tr>
<td>协议集描述</td>
<td><code>@Api</code></td>
<td>用于controller类上</td>
</tr>
<tr>
<td>对象属性</td>
<td><code>@ApiModelProperty</code></td>
<td>用在出入参数对象的字段上</td>
</tr>
<tr>
<td>协议描述</td>
<td><code>@ApiOperation</code></td>
<td>用在controller的方法上</td>
</tr>
<tr>
<td>Response集</td>
<td><code>@ApiResponses</code></td>
<td>用在controller的方法上</td>
</tr>
<tr>
<td>Response</td>
<td><code>@ApiResponse</code></td>
<td>用在 @ApiResponses里边</td>
</tr>
<tr>
<td>非对象参数集</td>
<td><code>@ApiImplicitParams</code></td>
<td>用在controller的方法上</td>
</tr>
<tr>
<td>非对象参数描述</td>
<td><code>@ApiImplicitParam</code></td>
<td>用在<code>@ApiImplicitParams</code>的方法里边</td>
</tr>
<tr>
<td>描述返回对象的意义</td>
<td><code>@ApiModel</code></td>
<td>用在返回对象类上</td>
</tr>
</tbody>
</table>
<p>api标记，用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：</p>
<pre><code>@Api(value = "/user", description = "用户管理")</code></pre>
<h3>与Controller注解并列使用。 属性配置：</h3>
<table>
<thead>
<tr>
<th>属性名称</th>
<th>备注</th>
</tr>
</thead>
<tbody>
<tr>
<td>value</td>
<td>url的路径值</td>
</tr>
<tr>
<td>tags</td>
<td>如果设置这个值、value的值会被覆盖</td>
</tr>
<tr>
<td>description</td>
<td>对api资源的描述</td>
</tr>
<tr>
<td>basePath</td>
<td>基本路径可以不配置</td>
</tr>
<tr>
<td>position</td>
<td>如果配置多个Api 想改变显示的顺序位置</td>
</tr>
<tr>
<td>produces</td>
<td>For example, "application/json, application/xml"</td>
</tr>
<tr>
<td>consumes</td>
<td>For example, "application/json, application/xml"</td>
</tr>
<tr>
<td>protocols</td>
<td>Possible values: http, https, ws, wss.</td>
</tr>
<tr>
<td>authorizations</td>
<td>高级特性认证时配置</td>
</tr>
<tr>
<td>hidden</td>
<td>配置为true 将在文档中隐藏</td>
</tr>
</tbody>
</table>