本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 API Gateway 中使用 OpenAPI 開發 REST API 您可以使用 API Gateway 將 REST API 從外部定義檔案匯入至 API Gateway。目前，API Gateway 支援 [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 和 [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 定義檔案，例外狀況列於 [適用於 REST API 的 Amazon API Gateway 重要說明](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis) 中。您可以用新的定義覆寫 API 來更新 API，或與現有的 API 合併定義。您可以在請求 URL 中使用 `mode` 查詢參數來指定選項。 如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。 **Topics** + [ # 將邊緣最佳化 API 匯入至 API Gateway ](import-edge-optimized-api.md) + [ # 將區域 API 匯入至 API Gateway ](import-export-api-endpoints.md) + [ # 匯入 OpenAPI 檔案以更新現有的 API 定義 ](api-gateway-import-api-update.md) + [ # 設定 OpenAPI `basePath` 屬性 ](api-gateway-import-api-basePath.md) + [ # AWS OpenAPI 匯入的 變數 ](import-api-aws-variables.md) + [ # 將 API 匯入 API Gateway 的錯誤和警告 ](api-gateway-import-api-errors-warnings.md) + [ # 從 API Gateway 匯出 REST API ](api-gateway-export-api.md) # 將邊緣最佳化 API 匯入至 API Gateway 您可以匯入 API OpenAPI 定義檔來建立新的邊緣最佳化 API，方法是指定 `EDGE` 端點類型做為匯入操作的額外輸入 (除了 OpenAPI 檔案之外)。您可以使用 API Gateway 主控台 AWS CLI或 AWS SDK 來執行此操作。 如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。 **Topics** + [ ## 使用 API Gateway 主控台匯入邊緣最佳化 API ](#import-edge-optimized-api-with-console) + [ ## 使用 匯入邊緣最佳化 API AWS CLI ](#import-edge-optimized-api-with-awscli) ## 使用 API Gateway 主控台匯入邊緣最佳化 API 若要使用 API Gateway 主控台匯入邊緣最佳化 API，請執行以下操作： 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇 **Create API (建立 API)**。 1. 在 **REST API** 下，選擇 **Import** (匯入)。 1. 複製 API 的 OpenAPI 定義並將它貼入程式碼編輯器，或選擇**選擇檔案**，從本機磁碟機載入 OpenAPI 檔案。 1. 對於 **API 端點類型**，選取**邊緣最佳化**。 1. 選擇**建立 API** 以開始匯入 OpenAPI 定義。 ## 使用 匯入邊緣最佳化 API AWS CLI 以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令會從 OpenAPI 定義檔案匯入 API，以建立新的邊緣最佳化 API： ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` 或將 `endpointConfigurationTypes` 查詢字串參數明確指定為 `EDGE`： ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # 將區域 API 匯入至 API Gateway 當您匯入 API 時，可以選擇 API 的區域端點組態。您可以使用 API Gateway 主控台 AWS CLI、 或 AWS SDK。 當您匯出 API 時，API 端點組態不會包含在匯出的 API 定義中。 如需從 API Gateway 主控台使用「匯入 API」功能的教學課程，請參閱[教學課程：匯入範例來建立 REST API](api-gateway-create-api-from-example.md)。 **Topics** + [ ## 使用 API Gateway 主控台匯入區域性 API ](#import-regional-api-with-console) + [ ## 使用 匯入區域 API AWS CLI ](#import-regional-api-with-awscli) ## 使用 API Gateway 主控台匯入區域性 API 若要使用 API Gateway 主控台匯入區域端點的 API，請執行下列動作： 1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。 1. 選擇 **Create API (建立 API)**。 1. 在 **REST API** 下，選擇 **Import** (匯入)。 1. 複製 API 的 OpenAPI 定義並將它貼入程式碼編輯器，或選擇**選擇檔案**，從本機磁碟機載入 OpenAPI 檔案。 1. 對於 **API 端點類型**，選取**區域**。 1. 選擇**建立 API** 以開始匯入 OpenAPI 定義。 ## 使用 匯入區域 API AWS CLI 以下 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 命令會匯入 OpenAPI 定義檔案，並將端點類型設為區域： ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # 匯入 OpenAPI 檔案以更新現有的 API 定義 您可以匯入 API 定義只更新現有的 API，無需變更其端點組態，以及階段與階段變數，或參考 API 金鑰。 匯入到更新操作可在兩種模式下進行：合併或覆寫。 當 API (`A`) 合併到另一個 (`B`)，如果兩個 API 不共用任何衝突的定義，則產生的 API 會保留 `A` 和 `B` 兩者的定義。發生衝突時，合併 API (`A`) 之方法定義會覆寫被合併 API (`B`) 的對應方法定義。例如，假設 `B` 已宣告以下列方法傳回 `200` 和 `206` 回應： ``` GET /a POST /a ``` 而 `A` 宣告以下列方法傳回 `200` 和 `400` 回應： ``` GET /a ``` 當 `A` 合併到 `B`，產生的 API 會產出以下方法： ``` GET /a ``` 傳回 `200` 和 `400` 回應，且 ``` POST /a ``` 傳回 `200` 和 `206` 回應。 合併 API 適用於您已將外部 API 定義分解成多個更小的組件，而且一次只想要套用其中一個組件的變更時。例如，如果多個小組負責 API 的不同組件並有不同速率的變更時，則可能會出現此情況。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會保持不變。 當 API (`A`) 覆寫另一個 API (`B`)，產生的 API 會採用覆寫的 API (`A`) 之定義。覆寫 API 適用於外部 API 定義包含完整的 API 定義時。在此模式下，現有 API 中的項目若在已匯入的定義中沒有特別定義，則會遭到刪除。 若要合併 API，請將 `PUT` 請求提交給 `https://apigateway..amazonaws.com/restapis/?mode=merge`。`restapi_id` 路徑參數值指定要與所提供的 API 定義合併的 API。 下列程式碼片段顯示 `PUT` 請求範例，其中會將 JSON 中的 OpenAPI API 定義做為承載與 API Gateway 中已指定的 API 合併。 ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` 合併更新操作可將兩個完整的 API 定義合併在一起。對於小型累加變更，您可以使用​[資源更新](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html)操作。 若要覆寫 API，請將 `PUT` 請求提交給 `https://apigateway..amazonaws.com/restapis/?mode=overwrite`。`restapi_id` 路徑參數指定要使用所提供 API 定義覆寫的 API。 下列程式碼片段顯示使用 JSON 格式 OpenAPI 定義的承載覆寫請求的範例： ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` 未指定 `mode` 查詢參數時，會假設使用合併。 **注意** `PUT` 操作為等冪，但不可部分完成。這表示如果在處理到一半時發生系統錯誤，API 最後可能會是錯誤狀態。不過，重複此操作會成功將 API 放到相同的最終狀態，就像是成功進行的第一個操作。 # 設定 OpenAPI `basePath` 屬性 在 [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 中，您可以使用 `basePath` 屬性來提供 `paths` 屬性中所定義之每個路徑之前的一或多個路徑部分。由於 API Gateway 表達資源路徑的方式有幾種，因此匯入 API 功能會在匯入期間提供下列選項來解譯 `basePath` 屬性：ignore、prepend 和 split。 在 [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/) 中，`basePath` 不再是頂層屬性。相反地，API Gateway 會使用[伺服器變數](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)做為慣例。匯入 API 功能會提供相同選項，以在匯入期間解譯基本路徑。基本路徑會依下列所述進行識別： + 如果 API 未包含任何 `basePath` 變數，則匯入 API 功能會檢查 `server.url` 字串，以查看其是否包含超過 `"/"` 的路徑。若是，該路徑會用作基本路徑。 + 如果 API 只包含一個 `basePath` 變數，則匯入 API 功能會使用它，做為基本路徑，即使未在 `server.url` 中參考它也一樣。 + 如果 API 包含多個 `basePath` 變數，則匯入 API 功能只會使用第一個變數，做為基本路徑。 ## Ignore 如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求： ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` 會導致 API 中的下列資源： + `/` + `/e` + `/f` 結果是將 `basePath` 視為不存在，並提供與主機相關之所有已宣告的 API 資源。例如，當您有自訂網域名稱，其 API 映射未包含 *Base Path (基底路徑)* 以及參考您生產階段的 *Stage (階段)* 值，就可以使用此選項。 **注意** API Gateway 會自動為您建立根資源，即使您的定義檔中沒有明確宣告也一樣。 未指定時，`basePath` 預設會採用 `ignore`。 ## 前綴 如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求： ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` 會導致 API 中的下列資源： + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` 結果是將 `basePath` 視為指定其他資源 (不含方法)，並將其新增至已宣告的資源集。例如，當不同小組負責 API 的不同組件，而且 `basePath` 可能參考每個小組之 API 組件的路徑位置時，就可以使用此選項。 **注意** API Gateway 會自動為您建立中繼資源，即使您的定義中沒有明確宣告也一樣。 ## Split 如果 OpenAPI 檔案具有 `basePath` 的 `/a/b/c` 值，而且 `paths` 屬性包含 `/e` 與 `/f`，則下列 `POST` 或 `PUT` 請求： ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` 會導致 API 中的下列資源： + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` 結果是將最上層的路徑部分 `/a` 視為每個資源路徑的開頭，並在 API 本身內建立其他資源 (不含方法)。例如，當 `a` 是您要公開為 API 一部分的階段名稱時，就可以使用此選項。 # AWS OpenAPI 匯入的 變數 您可以在 OpenAPI 定義中使用下列 AWS 變數。API Gateway 會在匯入 API 時解析變數。若要指定變數，請使用 `${variable-name}`。下表說明可用的 AWS 變數。 | 變數名稱 | Description | | --- | --- | | AWS::AccountId | 匯入 API AWS 的帳戶 ID。例如：123456789012。 | | AWS::Partition | 匯入 API 的 AWS 分割區。對於標準 AWS 區域，分割區為 aws。 | | AWS::Region | 匯入 API AWS 的區域。例如 us-east-2。 | ## AWS 變數範例 下列範例使用 AWS 變數來指定 整合的 AWS Lambda 函數。 ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # 將 API 匯入 API Gateway 的錯誤和警告 當您將外部定義檔案匯入 API Gateway 時，API Gateway 可能會產生警告和錯誤。下列各節討論匯入期間可能發生的錯誤和警告。 ## 匯入期間的錯誤 匯入期間，OpenAPI 文件無效等重大問題可能會產生錯誤。這些錯誤會在失敗回應中以例外狀況 (例如 `BadRequestException`) 傳回。發生錯誤時，會捨棄新的 API 定義，而且不會對現有的 API 進行變更。 ## 匯入期間的警告 匯入期間，遺失模型參考等次要問題可能會產生警告。如果發生警告，並將 `failonwarnings=false` 查詢表達式附加至請求 URL，操作將會繼續。否則會復原更新。根據預設，`failonwarnings` 會設定為 `false`。在此類情況下，警告會在所產生的 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 資源中的欄位回傳。否則，警告會以例外狀況中的訊息傳回。 # 從 API Gateway 匯出 REST API 一旦您使用 API Gateway 主控台或其他方式，在 API Gateway 中建立並配置 REST API，就可以使用 API Gateway Export API (屬於 Amazon API Gateway 控制服務的一部分) 將其匯出至 OpenAPI 檔案。若要使用 API Gateway Export API，您必須簽署 API 請求。如需簽署請求的詳細資訊，請參閱《*IAM 使用者指南*》中的[簽署 AWS API 請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。您可以選擇在匯出的 OpenAPI 定義檔中包含 API Gateway 整合延伸項目和 [Postman](https://www.postman.com) 延伸項目。 **注意** 使用 匯出 API 時 AWS CLI，請務必包含延伸項目參數，如下列範例所示，以確保包含`x-amazon-apigateway-request-validator`延伸項目： ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` 如果 API 的承載類型不是 `application/json`，則無法匯出 API。如果您嘗試，則會收到錯誤回應，指出找不到 JSON 內文模型。 ## 匯出 REST API 的請求 使用匯出 API 時，您可以提交 GET 請求並將欲匯出的 API 指定為 URL 路徑的一部分，藉此匯出現有 REST API。請求 URL 的格式如下： ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ 您可以附加 `extensions` 查詢字串，以指定要包含 API Gateway 延伸 (具有 `integration` 值) 或是 Postman 延伸 (具有 `postman` 值)。 此外，您也可以將 `Accept` 標頭設定為 `application/json` 或 `application/yaml`，分別接收 JSON 或 YAML 格式的 API 定義輸出。 如需使用 API Gateway Export API 提交 GET 請求的詳細資訊，請參閱 [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)。 **注意** 如果您在 API 中定義模型，則模型必須適用於內容類型「application/json」，API Gateway 才會匯出模型。否則，API Gateway 會擲回例外狀況，其錯誤訊息為「只發現 ... 的非 JSON 內文模型」。 模型必須包含屬性，或是定義為特定 JSONSchema 類型。 ## 下載 JSON 格式的 REST API OpenAPI 定義 以 JSON 格式的 OpenAPI 定義匯出並下載 REST API： ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ 例如，在這裡，`` 可以是 `us-east-1`。如需可使用 API Gateway 的所有區域，請參閱[區域和端點](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)。 ## 下載 YAML 格式的 REST API OpenAPI 定義 以 YAML 格式的 OpenAPI 定義匯出並下載 REST API： ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## 下載 JSON 格式且具有 Postman 延伸的 REST API OpenAPI 定義 以 JSON 格式的 OpenAPI 定義搭配 Postman 匯出並下載 REST API： ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## 下載 YAML 格式且具有 API Gateway 整合的 REST API OpenAPI 定義 以 YAML 格式的 OpenAPI 定義搭配 API Gateway 整合匯出並下載 REST API： ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## 使用 API Gateway 主控台匯出 REST API [將 REST API 部署至階段](set-up-deployments.md#create-deployment)之後，即可繼續使用 API Gateway 主控台，將階段中的 API 匯出至 OpenAPI 檔案。 在 API Gateway 主控台的**階段**窗格中，選擇**階段動作**、**匯出**。 ![\[使用 API Gateway 主控台匯出 REST API\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/export-new-console.png) 指定 **API 規格類型**、**格式**和**延伸模組**，以下載 API 的 OpenAPI 定義。