API Gateway 中的 API 文件表示

API Gateway API 文件是由與特定 API 實體相關聯的個別文件組件所組成，這些實體包括 API、資源、方法、請求、回應、訊息參數 (即路徑、查詢、標頭)，以及授權方與模型。

在 API Gateway 中，文件組件是以 DocumentationPart 資源表示。整個 API 文件是以 DocumentationParts 集合表示。

記錄 API 需要建立 DocumentationPart 執行個體、將其新增至 DocumentationParts 集合，並隨著 API 改進維護不同版本的文件組件。

文件組件

DocumentationPart 資源是存放適用於個別 API 實體之文件內容的 JSON 物件。其 properties 欄位包含對應鍵值對的文件內容。其 location 屬性識別相關聯的 API 實體。

內容對應的成形取決於身為 API 開發人員的您。金鑰/值對的值可以是字串、數值、布林值、物件或陣列。location 物件的成形取決於目標實體類型。

DocumentationPart 資源支援內容繼承：API 實體的文件內容適用於 API 實體的子系。如需子實體與內容繼承定義的詳細資訊，請參閱從較一般規格的 API 實體繼承內容。

文件組件的位置

DocumentationPart 執行個體的 location 屬性可辨識相關聯內容適用的 API 實體。該 API 實體可以是 API Gateway REST API 資源，例如 RestApi、Resource、Method、MethodResponse、Authorizer 或 Model。該實體也可以是訊息參數，例如 URL 路徑參數、查詢字串參數、請求或回應標頭參數、請求或回應內文，或是回應狀態碼。

若要指定 API 實體，請將 location 物件的 type 屬性設定為 API、AUTHORIZER、MODEL、RESOURCE、METHOD、PATH_PARAMETER、QUERY_PARAMETER、REQUEST_HEADER、REQUEST_BODY、RESPONSE、RESPONSE_HEADER 或 RESPONSE_BODY 其中之一。

根據 API 實體的 type，您可以指定其他 location 屬性，包括 method、name、path 與 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 會選擇具有最明確路徑值的實體。下表顯示一些範例。

以下是較泛型的 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 資源的有效與必要欄位，以及適用的預設值。

{
    "location": {
        "type": "API" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}

{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}

文件版本

文件版本是 API 之 DocumentationParts 集合的快照，並以版本識別符標記。發布 API 的文件需要建立文件版本、將其與 API 階段建立關聯，並將特定階段版本的 API 文件匯出到外部 OpenAPI 檔案。在 API Gateway 中，文件快照是以 DocumentationVersion 資源表示。

當您更新 API 時，您會建立新版的 API。在 API Gateway 中，您會使用 DocumentationVersions 集合維護所有文件版本。