Swagger注解-@ApiResponses 和 @ApiResponse

约定不等于承诺〃 2022-02-14 06:17 1596阅读 0赞

# @ApiResponses #

## 代码示例 ##

[github 代码示例： https://github.com/CoderFreeMan/swagger-demo][github _ https_github.com_CoderFreeMan_swagger-demo]

## 使用场景 ##

在 Rest 接口上使用，用作返回值的描述

## 概述 ##

一个包装器，允许列出多个 ApiResponse，若果你需要描述单个 ApiResponse，你仍然必须使用此注解并将@ApiResponse 包装在一个数组中

## 属性 ##

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>数据类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>value</td> 
   <td>ApiResponse[]</td> 
   <td></td> 
   <td>ApiResponse 列表</td> 
  </tr> 
 </tbody> 
</table>

# @ApiResponse #

## 使用场景 ##

在 Rest 接口或类上和 @ApiResponses 组合使用，组装返回参数说明

## 概述 ##

描述操作的可能响应，这可用于描述 Rest API 调用中可能的成功和错误 code 码。此注解可以在方法或类级别应用；仅当在方法级别或抛出时未定义相同代码的@ApiResponse注解时才会解析类级别注解异常，如果响应中使用了不同的响应类，则可以通过将响应类于响应码组合使用。注意swagger不允许单个响应代码的多个响应类型。此注解不直接使用，单独使用时swagger不会解析，应该和ApiResponses组合使用。

## 属性 ##

<table> 
 <thead> 
  <tr> 
   <th>属性名称</th> 
   <th>数据类型</th> 
   <th>默认值</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>code</td> 
   <td>int</td> 
   <td></td> 
   <td>响应的<a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" rel="nofollow">HTTP状态码</a></td> 
  </tr> 
  <tr> 
   <td>message</td> 
   <td>String</td> 
   <td></td> 
   <td>伴随响应的人类可读的消息</td> 
  </tr> 
  <tr> 
   <td>response</td> 
   <td>Class&lt;?&gt;</td> 
   <td>Void.class</td> 
   <td>用于描述消息有效负载的可选响应类，对应于响应消息对象的 schema 字段</td> 
  </tr> 
  <tr> 
   <td>reference</td> 
   <td>String</td> 
   <td>“”</td> 
   <td>指定对响应类型的引用，指定的应用可以使本地引用，也可以是远程引用，将按原样使用，并将覆盖任何指定的response()类</td> 
  </tr> 
  <tr> 
   <td>responseHeaders</td> 
   <td>ResponseHeader[]</td> 
   <td>@ResponseHeader(name = “”, response = Void.class)</td> 
   <td>可能响应的 header 列表</td> 
  </tr> 
  <tr> 
   <td>responseContainer</td> 
   <td>String</td> 
   <td>“”</td> 
   <td>声明响应的容器，有效值为List,Set,Map，任何其他值都将被忽略</td> 
  </tr> 
 </tbody> 
</table>

[github _ https_github.com_CoderFreeMan_swagger-demo]: https://github.com/CoderFreeMan/swagger-demo