本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # API Gateway 中的 API 文件表示 API Gateway API 文件是由與特定 API 實體相關聯的個別文件組件所組成，這些實體包括 API、資源、方法、請求、回應、訊息參數 (即路徑、查詢、標頭)，以及授權方與模型。 在 API Gateway 中，文件組件是以 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 資源表示。整個 API 文件是以 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html) 集合表示。 記錄 API 需要建立 `DocumentationPart` 執行個體、將其新增至 `DocumentationParts` 集合，並隨著 API 改進維護不同版本的文件組件。 **Topics** + [文件組件](#api-gateway-documenting-api-content-representation-documentation-parts) + [文件版本](#api-gateway-documenting-api-content-representation-documentation-versions) ## 文件組件 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 資源是存放適用於個別 API 實體之文件內容的 JSON 物件。這包括您文件的任何 UTF-8 內容和所有主要當地語系化語言。其 `properties` 欄位包含對應鍵值對的文件內容。其 `location` 屬性識別相關聯的 API 實體。 內容對應的成形取決於身為 API 開發人員的您。金鑰/值對的值可以是字串、數值、布林值、物件或陣列。`location` 物件的成形取決於目標實體類型。 `DocumentationPart` 資源支援內容繼承：API 實體的文件內容適用於 API 實體的子系。如需子實體與內容繼承定義的詳細資訊，請參閱[從較一般規格的 API 實體繼承內容](#api-gateway-documenting-api-content-inheritance)。 ### 文件組件的位置 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 執行個體的 [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) 屬性可辨識相關聯內容適用的 API 實體。該 API 實體可以是 API Gateway REST API 資源，例如 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)、[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)、[Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)、[MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)、[Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) 或 [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)。該實體也可以是訊息參數，例如 URL 路徑參數、查詢字串參數、請求或回應標頭參數、請求或回應內文，或是回應狀態碼。 若要指定 API 實體，請將 `location` 物件的 [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) 屬性設定為 `API`、`AUTHORIZER`、`MODEL`、`RESOURCE`、`METHOD`、`PATH_PARAMETER`、`QUERY_PARAMETER`、`REQUEST_HEADER`、`REQUEST_BODY`、`RESPONSE`、`RESPONSE_HEADER` 或 `RESPONSE_BODY` 其中之一。 根據 API 實體的 `type`，您可以指定其他 `location` 屬性，包括 [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method)、[name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name)、[path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) 與 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode)。並非所有屬性對指定的 API 實體都有效。例如，`type`、`path`、`name` 與 `statusCode` 是 `RESPONSE` 實體的有效屬性；但只有 `type` 與 `path` 是 `RESOURCE` 實體的有效 location 屬性。在指定 API 實體之 `location` 的 `DocumentationPart` 中包含無效的欄位是錯誤的。 並非所有有效的 `location` 欄位都是必要的。例如，`type` 是對所有 API 實體有效且必要的 `location` 欄位。不過，`method`、`path` 與 `statusCode` 對 `RESPONSE` 實體有效，但不是必要的屬性。未明確指定時，有效的 `location` 欄位會假設其預設值。預設 `path` 值是 `/`，即 API 的根資源。`method` 或 `statusCode` 的預設值是 `*`，分別表示任何方法或狀態碼值。 ### 文件組件的內容 `properties` 值已編碼為 JSON 字串。`properties` 值包含為符合您的文件需求所選擇的任何資訊。例如，以下是有效的內容對應： ``` { "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." } ``` 雖然 API Gateway 接受任何有效的 JSON 字串做為內容對應，但內容屬性會分為兩類來處理：OpenAPI 可識別的屬性與無法識別的屬性。在上述範例中，OpenAPI 將 `info`、`description` 與 `x-custom-info` 識別為標準 OpenAPI 物件、屬性或延伸。相較之下，`my-info` 與 OpenAPI 規格不相容。API Gateway 會將與 OpenAPI 相容的內容屬性從相關聯的 `DocumentationPart` 執行個體傳播到 API 實體定義中。API Gateway 不會將不相容的內容屬性傳播到 API 實體定義中。 在另一個範例中，`DocumentationPart` 實體的目標 `Resource` 如下： ``` { "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } } ``` 在本例中，`type` 與 `path` 都是可識別 `RESOURCE` 類型目標的有效欄位。對於根資源 (`/`)，您可以省略 `path` 欄位。 ``` { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } } ``` 這與下列 `DocumentationPart` 執行個體相同： ``` { "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } } ``` ### 從較一般規格的 API 實體繼承內容 選用之 `location` 欄位的預設值提供 API 實體的模式說明。使用 `location` 物件的預設值，您可以將 `properties` 映射中的一般說明新增至具有這種 `location` 模式類型的 `DocumentationPart` 執行個體。API Gateway 會從泛型 API 實體的 `DocumentationPart` 中擷取適用的 OpenAPI 文件屬性，再插入其 `location` 欄位符合一般 `location` 模式或符合確切值的特定 API 實體中，除非該特定實體已有相關聯的 `DocumentationPart` 執行個體。此行為也稱為來自較一般規格之 API 實體的內容繼承。 內容繼承不適用於特定 API 實體類型。如需詳細資訊，請參閱下列資料表。 當 API 實體符合多個 `DocumentationPart` 的位置模式時，實體會繼承具有最高優先順序與明確性之位置欄位的文件組件。優先順序為 `path` > `statusCode`。與 `path` 欄位比對時，API Gateway 會選擇具有最明確路徑值的實體。下表顯示一些範例。 | 案例 | `path` | `statusCode` | `name` | 備註 | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | id | 與此位置模式相關聯的文件會由符合位置模式的實體繼承。 | | 2 | /pets | 200 | id | 當案例 1 與案例 2 相符時，由於案例 2 比案例 1 更明確，因此與此位置模式相關聯的文件會由符合位置模式的實體繼承。 | | 3 | /pets/petId | \$1 | id | 當案例 1、2 與 3 相符時，由於案例 3 的優先順序比案例 2 高且比案例 1 更明確，因此與此位置模式相關聯的文件會由符合位置模式的實體繼承。 | 以下是較泛型的 `DocumentationPart` 執行個體與較明確的執行個體的另一個對比範例。下列一般錯誤訊息 `"Invalid request error"` 會插入 `400` 錯誤回應的 OpenAPI 定義，除非遭到覆寫。 ``` { "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" } ``` 透過下列覆寫，`/pets` 資源上任何方法的 `400` 回應會改為具有 `"Invalid petId specified"` 的說明。 ``` { "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" } ``` ### `DocumentationPart` 的有效位置欄位 下表顯示與指定 API 實體類型相關聯之 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 資源的有效與必要欄位，以及適用的預設值。 | API 實體 | 有效的位置欄位 | 必要的位置欄位 | 預設欄位值 | 是否可繼承內容 | | --- | --- | --- | --- | --- | | [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | 不適用 | 否 | | [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | path 的預設值為 /。 | 否 | | [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path 與 method 的預設值分別為 / 與 \$1。 | 是，符合 path 的字首，且符合任何值的 method。 | | 查詢參數 | 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
| type | path 與 method 的預設值分別為 / 與 \$1。 | 是，符合 path 的字首，且符合 method 的確切值。 | | 請求內文 | 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path 與 method 的預設值分別為 / 與 \$1。 | 是，符合 path 的字首，且符合 method 的確切值。 | | 請求標頭參數 | 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path 與 method 的預設值分別為 / 與 \$1。 | 是，符合 path 的字首，且符合 method 的確切值。 | | 請求路徑參數 | 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
| type, name | path 與 method 的預設值分別為 / 與 \$1。 | 是，符合 path 的字首，且符合 method 的確切值。 | | 回應 | 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path、method 與 statusCode 的預設值分別為 /、\$1 與 \$1。 | 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。 | | 回應標頭 | 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path、method 與 statusCode 的預設值分別為 /、\$1 與 \$1。 | 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。 | | 回應內文 | 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path、method 與 statusCode 的預設值分別為 /、\$1 與 \$1。 | 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。 | | [授權方](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | 不適用 | 否 | | [模型](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | 不適用 | 否 | ## 文件版本 文件版本是 API 之 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 集合的快照，並以版本識別符標記。發布 API 的文件需要建立文件版本、將其與 API 階段建立關聯，並將特定階段版本的 API 文件匯出到外部 OpenAPI 檔案。在 API Gateway 中，文件快照是以 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 資源表示。 當您更新 API 時，您會建立新版的 API。在 API Gateway 中，您會使用 [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 集合維護所有文件版本。