API網關中的API文檔表示 - Amazon API Gateway
文件組件文件版本

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

API網關中的API文檔表示

APIGateway 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閘道RESTAPI資源，例如資源RestApi、方法MethodResponse、授權者或模型。實體也可以是訊息參數，例如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屬性，包括方法、名稱、路徑和statusCode。並非所有這些屬性對於特定API實體都有效。例如，type、path、name 與 statusCode 是 RESPONSE 實體的有效屬性；但只有 type 與 path 是 RESOURCE 實體的有效 location 屬性。這是一個錯誤，包括一個無效location的字段在一個DocumentationPart給定的API實體。

並非所有有效的 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字串做為內容對應，但內容屬性會被視為兩個類別：可由 Open 辨識的類別API和無法辨識的類別。在前面的範例中，infodescription、和會x-custom-info被「開啟」識別API為標準的「開啟」API 物件、屬性或延伸模組。相反地，my-info不符合「開放」API 規格。API閘道會將與 Open 相容的內API容屬性從關聯DocumentationPart的執行個API體傳播到實體定義中。API閘道不會將不相容的內容屬性傳播到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 執行個體。APIGateway 會從泛型API實體擷取適用的 DocumentationPart Open API 文件屬性，並將它們注入具有與一般location模式相符的location欄位的特定API實體，或符合確切值，除非特定實體已有與其相關聯的DocumentationPart執行個體。這種行為也稱為來自更一般規格的API實體的內容繼承。

內容繼承不適用於某些API實體類型。如需詳細資訊，請參閱下列資料表。

當API實體符合多個DocumentationPart位置模式時，實體將繼承具有最高優先順序和特殊性位置欄位的說明文件零件。優先順序為 path > statusCode。為了與path欄位進行比對，APIGateway 會選擇具有最特定路徑值的實體。下表顯示一些範例。

案例 path statusCode name 備註
1 /pets * id

與此位置模式相關聯的文件會由符合位置模式的實體繼承。
2 /pets 200 id

當案例 1 與案例 2 相符時，由於案例 2 比案例 1 更明確，因此與此位置模式相關聯的文件會由符合位置模式的實體繼承。
3 /pets/petId * id

當案例 1、2 與 3 相符時，由於案例 3 的優先順序比案例 2 高且比案例 1 更明確，因此與此位置模式相關聯的文件會由符合位置模式的實體繼承。

以下是較泛型的 DocumentationPart 執行個體與較明確的執行個體的另一個對比範例。下列的一般錯誤訊息"Invalid request error"會插入錯400誤回應的 Open API 定義中，除非已覆寫。

{
    "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資源的適用預設值。

API 實體 有效的位置欄位 必要的位置欄位 預設欄位值 是否可繼承內容
API 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
 type 不適用 否
Resource 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
 type path 的預設值為 /。 否
方法 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type path 與 method 的預設值分別為 / 與 *。 是，符合 path 的字首，且符合任何值的 method。
查詢參數 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
 type path 與 method 的預設值分別為 / 與 *。 是，符合 path 的字首，且符合 method 的確切值。
請求內文 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
 type path 與 method 的預設值分別為 / 與 *。 是，符合 path 的字首，且符合 method 的確切值。
請求標頭參數 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
 type, name path 與 method 的預設值分別為 / 與 *。 是，符合 path 的字首，且符合 method 的確切值。
請求路徑參數 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
 type, name path 與 method 的預設值分別為 / 與 *。 是，符合 path 的字首，且符合 method 的確切值。
回應 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type path、method 與 statusCode 的預設值分別為 /、* 與 *。 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。
回應標頭 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
 type, name path、method 與 statusCode 的預設值分別為 /、* 與 *。 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。
回應內文 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
 type path、method 與 statusCode 的預設值分別為 /、* 與 *。 是，符合 path 的字首，且符合 method 與 statusCode 的確切值。
授權方 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
 type 不適用 否
模型 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
 type 不適用 否

文件版本

文件版本是DocumentationParts集合的快照，API並以版本識別元標記。發行的文件API包括建立文件版本、將其與階段產生關聯，以及將該API階段特定版本的文件匯出至外部 Open API 檔案。API在API閘道中，文件快照會表示為DocumentationVersion資源。

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