@apiresponse详解

@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的设计和实现也具有重要的意义。

原创文章，作者：小蓝，如若转载，请注明出处：https://www.506064.com/n/236787.html