使用 API Gateway 主控台記載 API

在本節中，我們會說明如何使用 API Gateway 主控台來建立及維護 API 的文件組件。

建立及編輯 API 文件的必要條件是您必須已建立 API。在本節中，我們以 PetStore API 為例。若要使用 API Gateway 主控台建立 API，請遵循教學課程：匯入範例來建立 REST API 中的說明進行。

記錄 API 實體

若要為 API 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取 API。

   如果未針對 API 建立文件組件，則會取得文件組件的 properties 對應編輯器。在文字編輯器中輸入下列 properties 映射。

   {
     "info": {
       "description": "Your first API Gateway API.",
       "contact": {
           "name": "John Doe",
           "email": "[e-mail]"
       }
     }
   }

   注意

   您不需要將 properties 對應編碼為 JSON 字串。API Gateway 主控台會為您字串化 JSON 物件。

3. 選擇建立文件組件。

若要在資源窗格中為 API 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇資源。

2. 選擇 API 動作選單，然後選擇更新 API 文件。

   

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 選取您的 API 名稱，然後在 API 卡片上選擇編輯。

記錄 RESOURCE 實體

若要為 RESOURCE 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取資源。

3. 在路徑中輸入路徑。

4. 在文字編輯器中輸入說明，例如：

   {
       "description": "The PetStore's root resource."
   }

5. 選擇建立文件組件。您可以為未列出的資源建立文件。

6. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要在資源窗格中為 RESOURCE 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇資源。

2. 選擇資源，然後選擇更新文件。

   

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 選取包含文件組件的資源，然後選擇編輯。

記錄 METHOD 實體

若要為 METHOD 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取方法。

3. 在路徑中輸入路徑。

4. 針對方法，選取 HTTP 動詞。

5. 在文字編輯器中輸入說明，例如：

   {
     "tags" : [ "pets" ],
     "summary" : "List all pets"
   }

6. 選擇建立文件組件。您可以為未列出的方法建立文件。

7. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要在資源窗格中為 METHOD 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇資源。

2. 選擇方法，然後選擇更新文件。

   

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取方法，或是選取包含該方法的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 QUERY_PARAMETER 實體

若要為 QUERY_PARAMETER 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取查詢參數。

3. 在路徑中輸入路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對名稱，輸入名稱。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的查詢參數建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取查詢參數，或是選取包含該查詢參數的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 PATH_PARAMETER 實體

若要為 PATH_PARAMETER 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取路徑參數。

3. 在路徑中輸入路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對名稱，輸入名稱。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的路徑參數建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取路徑參數，或是選取包含該路徑參數的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 REQUEST_HEADER 實體

若要為 REQUEST_HEADER 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取請求標頭。

3. 在路徑中，輸入請求標頭的路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對名稱，輸入名稱。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的請求標頭建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取請求標頭，或是選取包含該請求標頭的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 REQUEST_BODY 實體

若要為 REQUEST_BODY 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取請求內文。

3. 在路徑中，輸入請求內文的路徑。

4. 針對方法，選取 HTTP 動詞。

5. 在文字編輯器中輸入說明。

6. 選擇建立文件組件。您可以為未列出的請求內文建立文件。

7. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取請求內文，或是選取包含該請求內文的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 RESPONSE 實體

若要為 RESPONSE 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取回應 (狀態碼)。

3. 在路徑中，輸入回應的路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對狀態碼，輸入 HTTP 狀態碼。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的回應狀態碼建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取回應狀態碼，或是選取包含該回應狀態碼的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 RESPONSE_HEADER 實體

若要為 RESPONSE_HEADER 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取回應標頭。

3. 在路徑中，輸入回應標頭的路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對狀態碼，輸入 HTTP 狀態碼。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的回應標頭建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取回應標頭，或是選取包含該回應標頭的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 RESPONSE_BODY 實體

若要為 RESPONSE_BODY 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取回應內文。

3. 在路徑中，輸入回應內文的路徑。

4. 針對方法，選取 HTTP 動詞。

5. 針對狀態碼，輸入 HTTP 狀態碼。

6. 在文字編輯器中輸入說明。

7. 選擇建立文件組件。您可以為未列出的回應內文建立文件。

8. 如有需要，請重複這些步驟來新增或編輯其他文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇資源和方法索引標籤。

2. 您可以選取回應內文，或是選取包含該回應內文的資源，然後使用搜尋列尋找並選取您的文件組件。

3. 選擇編輯。

記錄 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. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取模型。

3. 針對名稱，輸入模型的名稱。

4. 在文字編輯器中輸入說明。

5. 選擇建立文件組件。您可以為未列出的模型建立文件。

6. 如果需要，請重複這些步驟來新增或編輯其他模型的文件組件。

若要在模型窗格中為 MODEL 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇模型。

2. 選擇模型，然後選擇更新文件。

   

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇模型索引標籤。

2. 使用搜尋列或選取模型，然後選擇編輯。

記錄 AUTHORIZER 實體

若要為 AUTHORIZER 實體新增文件組件，請執行下列動作：

1. 在主導覽窗格中，選擇文件，然後選擇建立文件組件。

2. 針對文件類型，選取授權方。

3. 在名稱中輸入授權方的名稱。

4. 在文字編輯器中輸入說明。針對授權方的有效 location 欄位指定值。

5. 選擇建立文件組件。您可以為未列出的授權方建立文件。

6. 如果需要，請重複這些步驟來新增或編輯其他授權方的文件組件。

若要編輯現有文件組件，請執行下列動作：

1. 在文件窗格中，選擇授權方索引標籤。

2. 使用搜尋列或選取授權方，然後選擇編輯。