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.<region>.amazonaws.com/restapis/<restapi_id>?mode=merge に送信します。restapi_id パスのパラメータ値は、指定された API 定義のマージ先となる API を示します。

次のコードスニペットは、指定された API がすでに API Gateway にあり、JSON の OpenAPI API 定義をペイロードとしてマージする PUT リクエストの例を示しています。

PUT /restapis/<restapi_id>?mode=merge
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON 
        

更新オペレーションのマージでは、2 つの完全な API 定義を使用し、それらをマージします。小さい増分変更の場合は、リソースの更新オペレーションを使用できます。

API をオーバーライドするには、PUT リクエストを https://apigateway.<region>.amazonaws.com/restapis/<restapi_id>?mode=overwrite に送信します。restapi_id パスパラメータは、指定された API 定義で上書きされる API を示します。

次のコードスニペットは、JSON 形式の OpenAPI 定義のペイロードでリクエストを上書きする例を示しています。

PUT /restapis/<restapi_id>?mode=overwrite
Host:apigateway.<region>.amazonaws.com
Content-Type: application/json
Content-Length: ...

An OpenAPI API definition in JSON 
            
        

mode クエリパラメータを指定しないと、マージが想定されます。