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 注解

ApiResponses 注解

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 ：

1. 一般而言，在实际项目开发中，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 ：

1. responseHeaders 属性值的定义应该按照 http 协议规定好的类别进行描述，如果我们所描述的不是 http 协议所规定的类型，那么在 Swagger 界面上是不会显示出来的，这点需要注意。
2. 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 ：

1. 在实际开发工作中，value 属性经常被用来描述一个接口方法的多条返回格式，其内容应该根据业务文档所规定的要求进行描述。
2. value 属性内容的填充形式就如上述代码所示，其中 value 这个单词可以不显式的写出来，Swagger 会默认隐藏。
3. ApiResponses 注解不能单独使用，因为他只有一个类型为 ApiResponse 数组形式的 value 属性，即要使用 ApiResponses 注解就必须要填充 value 属性。

5. 小结

本小节对 Swagger 中的 ApiResponse 和 ApiResponses 注解，及其该注解中的常用属性，做了详细介绍，针对两个注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式进行了重点介绍和应用剖析。

Tips : 值得注意的是 @ApiResponse 注解一般不可以单独拿来使用，需要搭配 @ApiResponses 注解一起来使用，这样才能在 Swagger-ui 界面看到使用效果。

在学习 ApiResponse 和 ApiResponses 注解及其常用属性时，各位同学应该在清楚常见的 http 状态码及其描述都有哪些以及什么是接口的请求头、响应头的基础上进行学习，因为这两个注解都是针对接口的返回数据及其格式而言的，其他地方无法使用。