# 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) 定義ファイルをサポートしています。この例外が「[Amazon API Gateway の REST API に関する重要な注意点](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis)」に記載されています。新しい定義で上書きして 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) + [OpenAPI インポート用の AWS 変数](import-api-aws-variables.md) + [API Gateway への API のインポートによるエラーと警告](api-gateway-import-api-errors-warnings.md) + [API Gateway から REST API をエクスポートする](api-gateway-export-api.md) # エッジ最適化 API を API Gateway にインポートする API OpenAPI 定義ファイルをインポートして、新しいエッジ最適化 API を作成できます。そのためには、OpenAPI ファイルに加えて `EDGE` エンドポイントタイプをインポートオペレーションへの入力として指定します。これは、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) + [AWS CLI を使用してエッジ最適化 API をインポートする](#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. [**API の作成**] を選択します。 1. [**REST API**] で、[**インポート**] を選択します。 1. API OpenAPI 定義をコピーしてコードエディタに貼り付けるか、**[ファイルの選択]** を選択してローカルドライブから OpenAPI ファイルを読み込みます。 1. **[エンドポイントタイプ]** で、**[エッジ最適化]** を選択します。 1. **[API の作成]** を選択して OpenAPI 定義のインポートを開始します。 ## AWS CLI を使用してエッジ最適化 API をインポートする 次の [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) + [AWS CLI を使用してリージョン API をインポートする](#import-regional-api-with-awscli) ## API Gateway コンソールを使用してリージョン API をインポートする API Gateway コンソールを使用してリージョンのエンドポイントの API をインポートするには、以下の手順を実行します。 1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) で API Gateway コンソールにサインインします。 1. [**API の作成**] を選択します。 1. [**REST API**] で、[**インポート**] を選択します。 1. API OpenAPI 定義をコピーしてコードエディタに貼り付けるか、**[ファイルの選択]** を選択してローカルドライブから OpenAPI ファイルを読み込みます。 1. **[API エンドポイントタイプ]** で、**[リージョン別]** を選択します。 1. **[API の作成]** を選択して OpenAPI 定義のインポートを開始します。 ## AWS CLI を使用してリージョン API をインポートする 次の [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 を更新する場合のみです。 インポートから更新への操作は、マージまたは上書きという 2 つのモードで行うことができます。 API (`A`) が別の API (`B`) にマージされると、作成された API では、2 つの 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 定義を複数の小さな部分に分解し、それらの部分の変更を一度に 1 つのみ適用する場合に役立ちます。たとえば、複数のチームが 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 を示します。 次のコードスニペットは、指定された API がすでに API Gateway にあり、JSON の OpenAPI API 定義をペイロードとしてマージする `PUT` リクエストの例を示しています。 ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` 更新オペレーションのマージでは、2 つの完全な 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` プロパティに定義された各パスに先行する 1 つ以上のパス部分を提供できます。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` 変数が 1 つだけの場合、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 マッピングや、本番ステージを参照する*ステージ*値を持つカスタムドメイン名がある場合です。 **注記** API Gateway は、定義ファイルに明示的に宣言されていない場合でも、自動的にルートリソースを作成します。 指定しない場合、`basePath` はデフォルトで `ignore` を受け取ります。 ## Prepend 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 の一部として公開するステージ名である場合です。 # OpenAPI インポート用の AWS 変数 OpenAPI 定義では、次の AWS 変数を使用できます。API Gateway は、API のインポート時に変数を解決します。変数を指定するには、`${variable-name}` を使用します。次の表は、使用可能な AWS 変数について説明しています。 | 変数名 | 説明 | | --- | --- | | 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 Gateway への API のインポートによるエラーと警告 外部定義ファイルを API Gateway にインポートすると、API Gateway で警告やエラーが発生することがあります。以下のセクションでは、インポート中に発生する可能性のあるエラーと警告について説明します。 ## インポート中のエラー インポート中に、無効な OpenAPI ドキュメントなど、大きな問題に対してエラーが生成される場合があります。エラーは、失敗のレスポンスの例外 (例: `BadRequestException`) として返されます。エラーが発生した場合、新しい API 定義は破棄され、既存の API は変更されません。 ## インポート中の警告 インポート中に、モデル参照の不足など、小規模な問題に対して警告が生成される場合があります。警告が発生した場合、リクエスト URL に `failonwarnings=false` クエリ式が追加されている場合、オペレーションは続行します。それ以外の場合、更新はロールバックされます。デフォルトで、`failonwarnings` は `false` に設定されています。このような場合、警告は [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) リソースのフィールドとして返されます。それ以外の場合、警告は例外のメッセージとして返されます。 # API Gateway から REST API をエクスポートする API Gateway で REST API を作成および設定したら、API Gateway コンソールなどから API Gateway Export API (Amazon API Gateway Control Service の一部です) を使用して、API を 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) 拡張機能を含めるオプションがあります。 **注記** AWS CLI を使用して API をエクスポートする場合、次の例に示すように extensions パラメータを必ず含めて、`x-amazon-apigateway-request-validator` 拡張子が含まれるようにします。 ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` ペイロードが `application/json` 型でない場合、API をエクスポートすることはできません。エクスポートを試みると、JSON 本文モデルが見つからないことを示すエラーレスポンスが返されます。 ## REST API をエクスポートするリクエスト Export API を使用すると、GET リクエストを送信し、URL パスの一部としてエクスポートされる API を指定することにより、既存の REST API をエクスポートします。リクエストの URL は次の形式です。 ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ `extensions` クエリ文字列を追加して、(値 `integration` を使用) API Gateway 拡張を含めるか、(値 `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 でモデルを定義する場合、モデルをエクスポートする API Gateway の "application/json" のコンテンツタイプである必要があります。それ以外の場合、API Gateway は「Only found non-JSON body models for ...」というエラーメッセージとともに例外をスローします。 モデルはプロパティを含むか、特定の JSONSchema 型として定義される必要があります。 ## REST API OpenAPI 定義を JSON でダウンロードする OpenAPI 定義を JSON 形式にして 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)」を参照してください。 ## REST API OpenAPI 定義を YAML でダウンロードする OpenAPI 定義を YAML 形式にして 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 ``` ------ ## Postman 拡張機能を使用して REST API OpenAPI 定義を JSON でダウンロードする Postman を使用して OpenAPI 定義を JSON 形式にして 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 ``` ------ ## API Gateway 統合を使用して REST API OpenAPI 定義ファイルを YAML でダウンロードする OpenAPI 定義を YAML 形式にして 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/ja_jp/apigateway/latest/developerguide/images/export-new-console.png) **[API 仕様タイプ]**、**[フォーマット]**、**[拡張機能]** を指定して API の OpenAPI 定義をダウンロードします。