API ドキュメントのインポート - Amazon API Gateway

API ドキュメントのインポート

API エンティティ定義のインポートと同様、ドキュメントパートは API Gateway で外部 OpenAPI ファイルから API にインポートできます。インポートするドキュメントパートは、有効な OpenAPI 定義ファイルの x-amazon-apigateway-documentation オブジェクト 拡張内で指定します。ドキュメントをインポートしても、既存の API エンティティ定義は変更されません。

API Gateway で新しく指定されたドキュメントパートを既存のドキュメントパートにマージしたり、既存のドキュメントパートを上書きしたりするオプションがあります。MERGE モードでは、OpenAPI ファイルで定義された新しいドキュメントパーツが API の DocumentationParts コレクションに追加されます。インポートする DocumentationPart がすでに存在する場合、2 つの属性が異なる場合はインポートされた属性によって既存の属性が置き換えられます。他の既存のドキュメント属性は影響を受けません。OVERWRITE モードでは、インポートされた OpenAPI 定義ファイルに従って DocumentationParts コレクション全体が置き換えられます。

API Gateway REST API を使用してドキュメントパートをインポートする

API Gateway REST API を使用して API ドキュメントをインポートするには、documentationpart:import オペレーションを呼び出します。次の例は、API の既存のドキュメントパーツを単一の GET / メソッドに置き換えて、成功時は 200 OK レスポンスを返す方法を示しています。

OpenAPI 3.0
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "openapi": "3.0.0", "info": { "description": "description", "version": "1", "title": "doc" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } } } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] }, "servers": [ { "url": "/" } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } }
OpenAPI 2.0
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "swagger": "2.0", "info": { "description": "description", "version": "1", "title": "doc" }, "host": "", "basePath": "/", "schemes": [ "https" ], "paths": { "/": { "get": { "description": "Method description.", "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] } }

成功すると、このリクエストはペイロードにインポートされた DocumentationPartId を含む 200 OK レスポンスを返します。

{ "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] }

加えて、API 定義の入力 OpenAPI ファイルの一部として x-amazon-apigateway-documentation オブジェクトでドキュメントパートを指定して、restapi:import または restapi:put を呼び出すこともできます。API インポートからドキュメントパーツを除外するには、リクエストクエリパラメータで ignore=documentation を設定します。

API Gateway コンソールを使用してドキュメントパートをインポートする

次の手順では、ドキュメントパーツをインポートする方法について説明します。

コンソールを使用して API のドキュメントパーツを外部ファイルからインポートするには
  1. メインナビゲーションペインで、[ドキュメント] を選択します。

  2. Import (インポート) を選択します。

  3. 既存のドキュメントがある場合は、新しいドキュメントを [上書き] するか [マージ] するかを選択します。

  4. [ファイルの選択] を選択してドライブからファイルをロードするか、ファイルのコンテンツをファイルビューに入力します。例として、「API Gateway REST API を使用してドキュメントパートをインポートする」にあるサンプルリクエストのペイロードを参照してください。

  5. インポート時の警告の処理方法を選択します。[警告を失敗とみなす] または [警告を無視する] を選択します。詳細については、「インポート中のエラーと警告」を参照してください。

  6. [Import] を選択します。