Swagger使用说明

一时失言乱红尘 2022-04-16 04:39 420阅读 0赞

# 使用说明 #

1、类、方法、参数、返回值上的注解必填

\--好处：前端可以识别参数名称

2、@Api上的tag 默认值为：类名；@ApiOperation 的tag默认值为版本号

\--好处：tag会自动归类，前端很容易看出当前版本的方法

**注意：类、方法、参数上的javadoc注释可以不写了**

# 示例 #

## 类 ##

![image2018-8-16_14-50-42.png_version_1_modificationDate_1534402244413_api_v2][]

## 方法 ##

![image2018-8-16_14-50-26.png_version_1_modificationDate_1534402228493_api_v2][]

## 参数 ##

![image2018-8-16_14-51-7.png_version_1_modificationDate_1534402269396_api_v2][]

## 返回值 ##

![image2018-8-16_14-52-49.png_version_1_modificationDate_1534402372016_api_v2][]

# Swagger 常用注解说明 #

<table> 
 <thead> 
  <tr> 
   <th>注解</th> 
   <th>属性</th> 
   <th>备注</th> 
   <th colspan="1">示例</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <th><code>@Api</code></th> 
   <td>value</td> 
   <td>可用在<code>class</code>头上,<code>class</code>描述</td> 
   <td colspan="1">@Api(value = "xxx", description = "xxx")</td> 
  </tr> 
  <tr> 
   <td>description</td> 
   <td>&nbsp;</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiOperation</code><br> &nbsp;</th> 
   <td>value</td> 
   <td>可用在方法头上.参数的描述容器</td> 
   <td colspan="1">@ApiOperation(value = "xxx", notes = "xxx", method = "GET")</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>说明</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>httpMethod</td> 
   <td>请求方法</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiImplicitParams</code></th> 
   <td>{}</td> 
   <td>可用在方法头上.参数的描述容器</td> 
   <td colspan="1">@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiImplicitParam</code><br><br><br><br><br><br> &nbsp;</th> 
   <td>name</td> 
   <td>可用在<code>@ApiImplicitParams</code>里</td> 
   <td colspan="1">@ApiImplicitParam(name = "newProduct", value = "商品信息对象", required = true, dataType = "Product", dataTypeClass = Product.class)</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>参数中文描述</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>required</td> 
   <td>true/false</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数类型</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>paramType</td> 
   <td> <p>参数请求方式:query/path</p> <p>query:对应<code>@RequestParam</code>传递</p> <p>path: 对应<code>@PathVariable</code>{}path传递</p> </td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>dataType</td> 
   <td>参数类型</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>dataTypeClass</td> 
   <td>参数对应的类</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>defaultValue</td> 
   <td>在api测试中默认值</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiResponses</code></th> 
   <td>{}</td> 
   <td>可用在方法头上.参数的描述容器</td> 
   <td colspan="1">@ApiResponses({@ApiResponse1,@ApiResponse2,...})</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiResponse</code><br> &nbsp;</th> 
   <td>code</td> 
   <td>可用在<code>@ApiResponses</code>里</td> 
   <td colspan="1">@ApiResponse(code = 200, message = "Successful", response = CommonResponse.class)</td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>错误描述</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>返回结果对应的类</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th>&nbsp;</th> 
   <th colspan="1">&nbsp;</th> 
  </tr> 
  <tr> 
   <th><code>@ApiModelProperty</code><br> &nbsp;</th> 
   <td>name</td> 
   <td>实体类参数名称</td> 
   <td colspan="1">@ApiModelProperty(name = "name", value = "name", notes = "名称")</td> 
  </tr> 
  <tr> 
   <td>value</td> 
   <td>实体类参数值</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
  <tr> 
   <td>notes</td> 
   <td>说明</td> 
   <td colspan="1">&nbsp;</td> 
  </tr> 
 </tbody> 
</table>

[image2018-8-16_14-50-42.png_version_1_modificationDate_1534402244413_api_v2]: http://wiki.firstshare.cn/download/attachments/76625121/image2018-8-16_14-50-42.png?version=1&modificationDate=1534402244413&api=v2
[image2018-8-16_14-50-26.png_version_1_modificationDate_1534402228493_api_v2]: http://wiki.firstshare.cn/download/attachments/76625121/image2018-8-16_14-50-26.png?version=1&modificationDate=1534402228493&api=v2
[image2018-8-16_14-51-7.png_version_1_modificationDate_1534402269396_api_v2]: http://wiki.firstshare.cn/download/attachments/76625121/image2018-8-16_14-51-7.png?version=1&modificationDate=1534402269396&api=v2
[image2018-8-16_14-52-49.png_version_1_modificationDate_1534402372016_api_v2]: http://wiki.firstshare.cn/download/attachments/76625121/image2018-8-16_14-52-49.png?version=1&modificationDate=1534402372016&api=v2