本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 API Gateway 主控台記載 API
在本節中，我們會說明如何使用 API Gateway 主控台來建立及維護 API 的文件組件。
建立及編輯 API 文件的必要條件是您必須已建立 API。在本節中，我們以 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API 為例。若要使用 API Gateway 主控台建立 API，請遵循[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md) 中的說明進行。
**Topics**
+ [記錄 `API` 實體](#api-gateway-document-api-add-document-part-for-api-entity-with-console)
+ [記錄 `RESOURCE` 實體](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [記錄 `METHOD` 實體](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [記錄 `QUERY_PARAMETER` 實體](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [記錄 `PATH_PARAMETER` 實體](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [記錄 `REQUEST_HEADER` 實體](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [記錄 `REQUEST_BODY` 實體](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [記錄 `RESPONSE` 實體](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [記錄 `RESPONSE_HEADER` 實體](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [記錄 `RESPONSE_BODY` 實體](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [記錄 `MODEL` 實體](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [記錄 `AUTHORIZER` 實體](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)
## 記錄 `API` 實體
若要為 `API` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取 **API**。
如果未針對 `API` 建立文件組件，則會取得文件組件的 `properties` 對應編輯器。在文字編輯器中輸入下列 `properties` 映射。
```
{
"info": {
"description": "Your first API Gateway API.",
"contact": {
"name": "John Doe",
"email": "john.doe@api.com"
}
}
}
```
**注意**
您不需要將 `properties` 對應編碼為 JSON 字串。API Gateway 主控台會為您字串化 JSON 物件。
1. 選擇**建立文件組件**。
若要在**資源**窗格中為 `API` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**資源**。
1. 選擇 **API 動作**選單，然後選擇**更新 API 文件**。
![\[在 API Gateway 主控台中編輯 API 實體的文件\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 選取您的 API 名稱，然後在 API 卡片上選擇**編輯**。
## 記錄 `RESOURCE` 實體
若要為 `RESOURCE` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**資源**。
1. 在**路徑**中輸入路徑。
1. 在文字編輯器中輸入說明，例如：
```
{
"description": "The PetStore's root resource."
}
```
1. 選擇**建立文件組件**。您可以為未列出的資源建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要在**資源**窗格中為 `RESOURCE` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**資源**。
1. 選擇資源，然後選擇**更新文件**。
![\[在 API Gateway 主控台中編輯資源實體的文件\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 選取包含文件組件的資源，然後選擇**編輯**。
## 記錄 `METHOD` 實體
若要為 `METHOD` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**方法**。
1. 在**路徑**中輸入路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 在文字編輯器中輸入說明，例如：
```
{
"tags" : [ "pets" ],
"summary" : "List all pets"
}
```
1. 選擇**建立文件組件**。您可以為未列出的方法建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要在**資源**窗格中為 `METHOD` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**資源**。
1. 選擇方法，然後選擇**更新文件**。
![\[在 API Gateway 主控台中編輯方法實體的文件\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取方法，或是選取包含該方法的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `QUERY_PARAMETER` 實體
若要為 `QUERY_PARAMETER` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**查詢參數**。
1. 在**路徑**中輸入路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**名稱**，輸入名稱。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的查詢參數建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取查詢參數，或是選取包含該查詢參數的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `PATH_PARAMETER` 實體
若要為 `PATH_PARAMETER` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**路徑參數**。
1. 在**路徑**中輸入路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**名稱**，輸入名稱。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的路徑參數建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取路徑參數，或是選取包含該路徑參數的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `REQUEST_HEADER` 實體
若要為 `REQUEST_HEADER` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**請求標頭**。
1. 在**路徑**中，輸入請求標頭的路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**名稱**，輸入名稱。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的請求標頭建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取請求標頭，或是選取包含該請求標頭的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `REQUEST_BODY` 實體
若要為 `REQUEST_BODY` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**請求內文**。
1. 在**路徑**中，輸入請求內文的路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的請求內文建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取請求內文，或是選取包含該請求內文的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `RESPONSE` 實體
若要為 `RESPONSE` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**回應 (狀態碼)**。
1. 在**路徑**中，輸入回應的路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**狀態碼**，輸入 HTTP 狀態碼。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的回應狀態碼建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取回應狀態碼，或是選取包含該回應狀態碼的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `RESPONSE_HEADER` 實體
若要為 `RESPONSE_HEADER` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**回應標頭**。
1. 在**路徑**中，輸入回應標頭的路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**狀態碼**，輸入 HTTP 狀態碼。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的回應標頭建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取回應標頭，或是選取包含該回應標頭的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `RESPONSE_BODY` 實體
若要為 `RESPONSE_BODY` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**回應內文**。
1. 在**路徑**中，輸入回應內文的路徑。
1. 針對**方法**，選取 HTTP 動詞。
1. 針對**狀態碼**，輸入 HTTP 狀態碼。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的回應內文建立文件。
1. 如有需要，請重複這些步驟來新增或編輯其他文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**資源和方法**索引標籤。
1. 您可以選取回應內文，或是選取包含該回應內文的資源，然後使用搜尋列尋找並選取您的文件組件。
1. 選擇**編輯**。
## 記錄 `MODEL` 實體
記錄 `MODEL` 實體需要建立及管理模型與每個模型之 `DocumentPart` 的 `properties` 執行個體。例如，每個 API 隨附的 `Error` 模型預設具有下列結構描述定義：
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
且需要兩個 `DocumentationPart` 執行個體，一個用於 `Model`，另一個用於其 `message` 屬性：
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
以及
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
匯出 API 之後，`DocumentationPart` 的屬性會覆寫原始結構描述中的值。
若要為 `MODEL` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**模型**。
1. 針對**名稱**，輸入模型的名稱。
1. 在文字編輯器中輸入說明。
1. 選擇**建立文件組件**。您可以為未列出的模型建立文件。
1. 如果需要，請重複這些步驟來新增或編輯其他模型的文件組件。
若要在**模型**窗格中為 `MODEL` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**模型**。
1. 選擇模型，然後選擇**更新文件**。
![\[在 API Gateway 主控台中編輯模型實體的文件\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**模型**索引標籤。
1. 使用搜尋列或選取模型，然後選擇**編輯**。
## 記錄 `AUTHORIZER` 實體
若要為 `AUTHORIZER` 實體新增文件組件，請執行下列動作：
1. 在主導覽窗格中，選擇**文件**，然後選擇**建立文件組件**。
1. 針對**文件類型**，選取**授權方**。
1. 在**名稱**中輸入授權方的名稱。
1. 在文字編輯器中輸入說明。針對授權方的有效 `location` 欄位指定值。
1. 選擇**建立文件組件**。您可以為未列出的授權方建立文件。
1. 如果需要，請重複這些步驟來新增或編輯其他授權方的文件組件。
若要編輯現有文件組件，請執行下列動作：
1. 在**文件**窗格中，選擇**授權方**索引標籤。
1. 使用搜尋列或選取授權方，然後選擇**編輯**。