@apiresponse是Swagger/OpenAPI中的一个重要的注解，在文档生成、接口测试和接口调试中都有着重要的作用。本文将从多个方面对@apiresponse进行详细阐述。
一、@apiresponse的概述
@apiresponse是Swagger/OpenAPI中的注解之一，用于标注API操作返回的响应体的数据结构以及相关的响应码和响应消息。
语法格式如下：
@apiresponse {
响应码 响应消息 {
响应体数据结构
}
}
具体来说，响应码是指返回的HTTP状态码，响应消息是指返回的HTTP状态码对应的文本描述，响应体数据结构是指返回的响应体的JSON数据结构，其格式与API操作定义的请求体数据结构类似。
@apiresponse可以出现在类级别或方法级别上。对于类级别@apiresponse，它用于定义类中所有API操作的通用响应信息，对于方法级别@apiresponse，它用于覆盖类级别@apiresponse，或者给特定的API操作设置详细的响应信息。
二、@apiresponse的使用方法
在使用@apiresponse时，需要按照以下步骤进行：
1.定义数据结构
在定义响应体数据结构时，可以使用Swagger/OpenAPI支持的jsonschema规范，也可以使用普通的JSON格式。
例如，下面是一个使用jsonschema规范定义的响应体数据结构：
{
"type": "object",
"properties": {
"id": {"type": "string"},
"name": {"type": "string"},
"age": {"type": "integer"},
"address": {
"type": "object",
"properties": {
"province": {"type": "string"},
"city": {"type": "string"}
},
"required": ["province", "city"]
}
},
"required": ["id", "name", "age"]
}
2.使用@apiresponse定义响应信息
在使用@apiresponse定义响应信息时，可以定义多个响应码和响应体数据结构，每个响应码对应一个响应体数据结构，响应消息是可选的。
例如，下面是使用@apiresponse定义GET操作响应信息的示例：
/**
* 获取用户信息
*
* @api {get} /users/:id 获取指定用户信息
* @apiGroup Users
* @apiParam {string} id 用户ID
* @apiSuccessExample {json} 成功响应示例
* HTTP/1.1 200 OK
* {
* "id": "123",
* "name": "张三",
* "age": 30,
* "address": {
* "province": "北京市",
* "city": "海淀区"
* }
* }
* @apiresponse {
* 200 成功获取用户信息 {
* "type": "object",
* "properties": {
* "id": {"type": "string"},
* "name": {"type": "string"},
* "age": {"type": "integer"},
* "address": {
* "type": "object",
* "properties": {
* "province": {"type": "string"},
* "city": {"type": "string"}
* },
* "required": ["province", "city"]
* }
* },
* "required": ["id", "name", "age"]
* }
* 404 未找到指定用户 {}
* 500 服务器内部错误 {}
* }
*/
public User getUser(String id) {
// ...获取用户信息
}
上面的示例中，定义了三个响应码（200、404、500）和对应的响应体数据结构。其中，200对应成功获取用户信息，404对应未找到指定用户，500对应服务器内部错误。每个响应体数据结构都是一个jsonschema格式的JSON对象，描述了API操作返回的响应体结构。
三、@apiresponse的高级用法
1.定义通用响应信息
可以在类级别上使用@apiresponse定义通用响应信息，这些通用响应信息可以被所有API操作继承。
例如，下面是使用@apiresponse定义通用响应信息的示例：
/**
* 用户管理API
*/
@apiresponse {
200 操作成功 {}
400 请求参数错误 {}
401 未登录或登录过期 {}
403 没有操作权限 {}
500 服务器内部错误 {}
}
public class UserController {
/**
* 获取用户信息
*/
@apiresponse {
200 成功获取用户信息 {}
404 用户不存在 {}
}
@GetMapping("/users/{id}")
public User getUser(@PathVariable String id) {
// ...获取用户信息
}
/**
* 删除用户
*/
@apiresponse {
204 删除成功 {}
404 用户不存在 {}
}
@DeleteMapping("/users/{id}")
public void deleteUser(@PathVariable String id) {
// ...删除用户
}
// ...其他API操作
}
在此示例中，使用@apiresponse在类级别上定义了通用的响应信息，包括常见的响应码和对应的消息文本。在具体的API操作上，可以使用@apiresponse覆盖类级别上的响应信息，并定义特定的响应组合方式。
2.使用多个@apiresponse
对于一个API操作，可以使用多个@apiresponse定义不同的响应信息组合。
例如，下面是使用多个@apiresponse定义不同的响应信息组合的示例：
/**
* 获取用户信息
*
* @api {get} /users/:id 获取指定用户信息
* @apiGroup Users
* @apiParam {string} id 用户ID
* @apiSuccessExample {json} 成功响应示例
* HTTP/1.1 200 OK
* {
* "id": "123",
* "name": "张三",
* "age": 30,
* "address": {
* "province": "北京市",
* "city": "海淀区"
* }
* }
* @apiresponse {
* 200 成功获取用户信息 {
* "type": "object",
* "properties": {
* "id": {"type": "string"},
* "name": {"type": "string"},
* "age": {"type": "integer"},
* "address": {
* "type": "object",
* "properties": {
* "province": {"type": "string"},
* "city": {"type": "string"}
* },
* "required": ["province", "city"]
* }
* },
* "required": ["id", "name", "age"]
* }
* 404 未找到指定用户 {}
* 500 服务器内部错误 {}
* }
* @apiresponse {
* 401 未登录或登录过期 {}
* 403 没有操作权限 {}
* }
*/
public User getUser(String id) {
// ...获取用户信息
}
在此示例中，第一个@apiresponse定义了200、404和500对应的响应信息，第二个@apiresponse定义了401和403对应的响应信息。不同的@apiresponse可以定义不同的响应码和响应消息文本，使得API操作可以灵活地处理不同场景下的响应信息。
3.使用@apiresponse覆盖类级别信息
在API操作级别上使用@apiresponse时，可以覆盖类级别上定义的通用响应信息。
例如，下面是在API操作级别上使用@apiresponse覆盖类级别信息的示例：
/**
* 获取用户信息
*/
@apiresponse {
200 成功获取用户信息 {}
404 用户不存在 {}
}
@GetMapping("/users/{id}")
@apiresponse {
401 未登录或登录过期 {}
}
public User getUser(@PathVariable String id) {
// ...获取用户信息
}
在此示例中，类级别@apiresponse定义了200和404对应的响应信息，在getUser方法上使用@apiresponse覆盖了类级别上对应的401响应信息。这种机制可以让API操作具有更高的灵活性和可控性。
四、总结
本文详细阐述了@apiresponse的概念、用法和高级用法，介绍了如何使用@apiresponse定义API操作的响应信息，并从多个方面深入阐述了其使用方法。@apiresponse是Swagger/OpenAPI规范中的一个重要注解，对于API的文档生成、测试和调试都有重要的作用，对于API的设计和实现也具有重要的意义。
