メニュー
Amazon API Gateway
開発者ガイド

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

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

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

API Gateway REST API を使用したドキュメントパーツのインポート

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

Copy
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 レスポンスを返します。

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

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

API Gateway コンソールを使用したドキュメントパーツのインポート

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

コンソールを使用して API のドキュメントパーツを外部ファイルからインポートするには

  1. コンソールで、メインナビゲーションペインから API の [Documentation] を選択します。

  2. [Documentation] ペインで [Import Documentation] を選択します。

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

  4. オプションで、[Fail on warnings] または [Ignore warnings] を選択し、[Import mode] から [Merge] または [Overwrite] を選択します。

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