Swagger-ApiResponse 和 ApiResponses 注解
1. 前言
本节会继续结合用户登录接口方法来为大家介绍 Swagger 中的两个关联注解 - ApiResponse 和 ApiResponses 注解及所提供的常用属性，使用率较低或基本不适用的注解属性就不再介绍了。
ApiResponse 和 ApiResponses 注解在实际项目中的使用频率较前面所介绍的注解而言相对较低，我们只需要掌握他们最的基本用法和常用属性即可。
重点讲解的属性：
-
ApiResponse 注解的 code 、message 、responseHeaders 属性；
-
ApiResponses 注解的 value 属性。
2. 什么是 ApiResponse 和 ApiResponses 注解 ？
ApiResponse 注解是作用在接口方法上的注解，用来对该接口方法的一个或多个返回值进行描述，一般不会单独使用，常常和 @ApiResponses 注解配合使用。
ApiResponses 注解也是作用在接口方法上的注解，作用和 @ApiResponse 注解相同，只是在当有多个 @ApiResponse 注解同时存在时才会使用该注解。
ApiResponse 和 ApiResponses 注解是一组关系紧密的注解，主要使用的属性都在 @ApiResponse 注解中。
下面我们来看一下 ApiResponse 和 ApiResponses 两个注解中都包括哪些常用属性。
3. 注解主要属性汇总
ApiResponse 注解
| 属性名称 | 属性类型 | 默认值 | 作用 |
|---|---|---|---|
| code() | int | 空 | 定义接口响应状态码 |
| message() | String | 空 | 定义接口响应状态码描述 |
| responseHeaders() | ResponseHeader | @ResponseHeader(name = “”, response = Void.class) | 定义接口响应头 |
ApiResponses 注解
| 属性名称 | 属性类型 | 默认值 | 作用 |
|---|---|---|---|
| value() | ApiResponse[] | 空 | 定义接口响应组 |
4. 属性详解
4.1 ApiResponse 注解相关属性
code () 和 message () 属性
定义：
code 属性就是描述接口返回的响应数据的状态码。
message 属性就是对接口返回的响应数据的状态码进行描述。
使用方法：
在 ApiResponse 注解中直接声明 code 属性和 message 属性的值即可，例如，对于用户登录接口，我想添加一个值为 666 的状态码，其描述为 success ，代表当接口返回的状态码为 666 时表示请求是成功（success）的。
鉴于上述业务场景，我们可以这样写：code = 666, message = “success”(现在你不需要理解业务代码代表什么意思，重点看实体类上使用的注解及属性即可，下同 。
@ApiResponse(code = 666, message = "success")
public ServerResponse<User> login(User user){
// do something...
}
代码解释：
第 1 行，我们在用户登录接口方法的上方定义了 ApiResponse 注解的 code 属性的值为 666，message 属性的值为 success 来对用户登录接口添加特定的返回信息。
显示结果：
可以看到，在用红框框起来的地方就是我们使用 code 属性和 message 属性所展示的效果了。
Tips ：
- 一般而言，在实际项目开发中，http 协议自带的返回状态码已经够用了，不需要开发者再特殊指定，如果业务要求必须遵照一定的规则，那就只能额外规定了。
responseHeaders () 属性
定义：
该属性就是对接口的返回头做一个描述，即犹如请求接口时所规定的请求头为 ‘application/json’ 类型那样。
使用方法：
在 ApiResponse 注解中，直接声明 responseHeaders 属性的值即可，例如，我想把用户登录接口的返回头类型定义为‘multipart/file’ (这样定义显然是不合理的，这里只做演示) ，则可以这样写：description = “用户实体中包含用户相关的所有业务字段，如有需要请另行添加” 。
@ApiResponse(code = 666, message = "success", responseHeaders = { @ResponseHeader(name = "userLoginHeader", description = "multipart/file") }),
public ServerResponse<User> login(User user){
// do something...
}
代码解释：
第 1 行，我们在用户实体类的上方定义了 responseHeaders 属性的值来对用户登录接口的返回头类型添加额外的描述信息。由于篇幅原因这里就不给大家截图了。
Tips ：
- responseHeaders 属性值的定义应该按照 http 协议规定好的类别进行描述，如果我们所描述的不是 http 协议所规定的类型，那么在 Swagger 界面上是不会显示出来的，这点需要注意。
- responseHeaders 属性虽然是 ApiResponse 注解中的，但是使用该属性需要以数组的形式使用，即如上述代码示例，因为该注解源码中就是这样定义的。
4.2 ApiResponses 注解相关属性
value () 属性
定义：
ApiResponses 注解的 value 属性就是对接口的返回状态码及其返回状态码描述进行多条描述，来说明该接口的返回格式有多条额外的描述。
使用方法：
ApiResponses 注解规定其 value 属性的类型为 ApiResponse 数组类型，这就说明 value 属性只能使用 @ApiResponse 注解的形式进行描述，同时允许描述多条。
例如，在用户登录接口中，我想对该接口的返回格式添加两条额外描述信息，使用方法如下所示。
@ApiResponses( value = {
@ApiResponse(code = 666, message = "success"),
@ApiResponse(code = 600, message = "error",)})
public ServerResponse<User> login(User user){
// do something...
}
代码解释：
1-3 行，我们在用户登录接口方法的上方定义了 ApiResponses 注解的 value 属性来对该接口的返回格式添加两条额外描述信息。
显示结果：
可以看到，600 和 666 及其 error 和 success 就是我们使用 value 属性来对该接口的返回格式添加的额外描述信息了。
Tips ：
- 在实际开发工作中，value 属性经常被用来描述一个接口方法的多条返回格式，其内容应该根据业务文档所规定的要求进行描述。
- value 属性内容的填充形式就如上述代码所示，其中 value 这个单词可以不显式的写出来，Swagger 会默认隐藏。
- ApiResponses 注解不能单独使用，因为他只有一个类型为 ApiResponse 数组形式的 value 属性，即要使用 ApiResponses 注解就必须要填充 value 属性。
5. 小结
本小节对 Swagger 中的 ApiResponse 和 ApiResponses 注解，及其该注解中的常用属性，做了详细介绍，针对两个注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式进行了重点介绍和应用剖析。
Tips : 值得注意的是 @ApiResponse 注解一般不可以单独拿来使用，需要搭配 @ApiResponses 注解一起来使用，这样才能在 Swagger-ui 界面看到使用效果。
在学习 ApiResponse 和 ApiResponses 注解及其常用属性时，各位同学应该在清楚常见的 http 状态码及其描述都有哪些以及什么是接口的请求头、响应头的基础上进行学习，因为这两个注解都是针对接口的返回数据及其格式而言的，其他地方无法使用。
- 还没有人评论，欢迎说说您的想法！
客服
