@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/zh-hk/n/236787.html