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

API ドキュメントの発行

API のドキュメントを発行するには、ドキュメントスナップショットを作成、更新、または取得した後、ドキュメントスナップショットを API ステージに関連付けます。ドキュメントスナップショットを作成するとき、同時に API ステージに関連付けることもできます。

ドキュメントスナップショットの作成と API ステージへの関連付け

API のドキュメントパーツのスナップショットを作成し、同時に API ステージと関連付けるには、次の POST リクエストを送信します。

Copy
POST /restapis/restapi_id/documentation/versions HTTP/1.1 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 { "documentationVersion" : "1.0.0", "stageName": "prod", "description" : "My API Documentation v1.0.0" }

成功した場合、オペレーションは新しく作成された DocumentationVersion インスタンスをペイロードとして含む、200 OK レスポンスを返します。

または、最初は API ステージに関連付けずにドキュメントスナップショットを作成してから、restapi:update を呼び出してスナップショットを指定した API ステージに関連付けることもできます。既存のドキュメントスナップショットの更新またはクエリを実行してから、そのステージの関連付けを更新することもできます。次の 4 つのセクションでは、そのステップを示します。

ドキュメントスナップショットの作成

API のドキュメントパーツのスナップショットを作成するには、新しい DocumentationVersion リソースを作成し、API の DocumentationVersions コレクションに追加します。

Copy
POST /restapis/restapi_id/documentation/versions HTTP/1.1 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 { "documentationVersion" : "1.0.0", "description" : "My API Documentation v1.0.0" }

成功した場合、オペレーションは新しく作成された DocumentationVersion インスタンスをペイロードとして含む、200 OK レスポンスを返します。

ドキュメントスナップショットの更新

ドキュメントスナップショットは、対応する DocumentationVersion リソースの description プロパティを変更することによってのみ更新できます。次の例は、そのバージョン識別子 version (1.0.0 など) によって識別されたとおりに、ドキュメントスナップショットの説明を更新する方法を示しています。

Copy
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1 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 { "patchOperations": [{ "op": "replace", "path": "/description", "value": "My API for testing purposes." }] }

成功した場合、オペレーションは更新された DocumentationVersion インスタンスをペイロードとして含む、200 OK レスポンスを返します。

ドキュメントスナップショットの取得

ドキュメントスナップショットを取得するには、指定された DocumentationVersion リソースに対して GET リクエストを送信します。次の例は、特定のバージョン識別子 1.0.0 のドキュメントスナップショットを取得する方法を示しています。

Copy
GET /restapis/<restapi_id>/documentation/versions/1.0.0 HTTP/1.1 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

API ステージへのドキュメントスナップショットの関連付け

API ドキュメントを発行するには、ドキュメントスナップショットを API ステージに関連付けます。ドキュメントバージョンをステージに関連付ける前に、API ステージをすでに作成している必要があります。

API Gateway REST API を使用してドキュメントスナップショットを API ステージに関連付けるには、stage:update オペレーションを呼び出して stage.documentationVersion プロパティに必要なドキュメントバージョンを設定します。

Copy
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME 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 { "patchOperations": [{ "op": "replace", "path": "/documentationVersion", "value": "VERSION_IDENTIFIER" }] }

次の手順では、ドキュメントバージョンを発行する方法について説明します。

API Gateway コンソールを使用してドキュメントバージョンを発行するには

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

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

  3. 出版物をセットアップします。

    1. [Stage] で使用可能な名前を選択します。

    2. [Version] にバージョン識別子 (1.0.0 など) を入力します。

    3. オプションで、[Description] に出版物に関する説明を入力します。

  4. [Publish] を選択します。

これで、ドキュメントを Swagger ファイルにエクスポートすることにより、発行されたドキュメントのダウンロードに進むことができるようになります。

ステージに関連付けられたドキュメントスナップショットのダウンロード

ドキュメントパーツのバージョンがステージに関連付けられたら、API Gateway コンソール、API Gateway REST API、その SDK のいずれか、または API Gateway 用の AWS CLI を使用して、ドキュメントパーツと API エンティティ定義を外部ファイルにエクスポートできます。プロセスは、API のエクスポートと同じです。エクスポートされるファイルの形式は、JSON または YAML です。

API Gateway REST API を使用すると、API ドキュメントパーツ、API 統合およびオーソライザーが API エクスポートに含められるように extension=documentation,integrations,authorizers クエリパラメーターを明示的に設定することもできます。デフォルトでは、API のエクスポート時、ドキュメントパーツは含められますが、統合とオーソライザーは含められません。API エクスポートからのデフォルト出力は、ドキュメントの配付に適しています。

API Gateway REST API を使用して外部 JSON Swagger ファイルに API ドキュメントをエクスポートするには、次の GET リクエストを送信します。

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1 Accept: application/json 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

ここでは、x-amazon-apigateway-documentation オブジェクトにドキュメントパーツが含まれており、API エンティティ定義に Swagger によりサポートされているドキュメントプロパティが含まれています。出力には、統合やカスタムオーソライザーの詳細は含まれていません。両方の詳細を含めるには、extensions=integrations,authorizers,documentation を設定します。オーソライザーの詳細は含めず統合の詳細を含めるには、extensions=integrations,documentation を設定します。

JSON ファイルで結果を出力するには、リクエストで Accept:application/json ヘッダーを設定する必要があります。YAML 出力を生成するには、リクエストヘッダーを Accept:application/yaml に変更します。

例として、ルートリソース (/) でシンプルな GET メソッドを開示する API について調べます。この API には、Swagger 定義ファイルで定義された 4 つの API エンティティ (それぞれ APIMODELMETHOD、および RESPONSE タイプ用) があります。ドキュメントパーツは、APIMETHODRESPONSE の各エンティティに追加されています。前の documentation-exporting コマンドを呼び出すと、次の出力が生成され、標準 Swagger ファイルへの拡張として x-amazon-apigateway-documentation オブジェクト内にドキュメントパーツがリストされます。

Copy
{ "swagger" : "2.0", "info" : { "description" : "API info description", "version" : "2016-11-22T22:39:14Z", "title" : "doc", "x-bar" : "API info x-bar" }, "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com", "basePath" : "/test", "schemes" : [ "https" ], "paths" : { "/" : { "get" : { "description" : "Method description.", "produces" : [ "application/json" ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/Empty" } } }, "x-example" : "x- Method example" }, "x-bar" : "resource x-bar" } }, "definitions" : { "Empty" : { "type" : "object", "title" : "Empty Schema" } }, "x-amazon-apigateway-documentation" : { "version" : "1.0.0", "createdDate" : "2016-11-22T22:41:40Z", "documentationParts" : [ { "location" : { "type" : "API" }, "properties" : { "description" : "API description", "foo" : "API foo", "x-bar" : "API x-bar", "info" : { "description" : "API info description", "version" : "API info version", "foo" : "API info foo", "x-bar" : "API info x-bar" } } }, { "location" : { "type" : "METHOD", "method" : "GET" }, "properties" : { "description" : "Method description.", "x-example" : "x- Method example", "foo" : "Method foo", "info" : { "version" : "method info version", "description" : "method info description", "foo" : "method info foo" } } }, { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "resource description", "foo" : "resource foo", "x-bar" : "resource x-bar", "info" : { "description" : "resource info description", "version" : "resource info version", "foo" : "resource info foo", "x-bar" : "resource info x-bar" } } } ] }, "x-bar" : "API x-bar" }

ドキュメントパーツの properties マップで定義された Swagger に準拠する属性の場合、API Gateway は関連付けられた API エンティティ定義に属性を挿入します。x-something の属性は、標準 Swagger 拡張です。この拡張は、API エンティティ定義に伝達されます。たとえば、GET メソッドの x-example 属性を参照してください。foo などの属性は、Swagger 仕様の一部ではないため、関連付けられた API エンティティ定義には挿入されません。

ドキュメントレンダリングツール (Swagger UI など) が API エンティティ定義を解析してドキュメント属性を抽出する場合、DocumentationPart インスタンスの Swagger に準拠していない properties 属性はどれもツールで使用できません。一方、ドキュメントレンダリングツールが x-amazon-apigateway-documentation オブジェクトを解析してコンテンツを取得するか、ツールが restapi:documentation-parts および documenationpart:by-id を呼び出して API Gateway からドキュメントパーツを取得する場合、ツールでの表示にすべてのドキュメント属性を使用できます。

ドキュメントと、統合の詳細を含む API エンティティ定義を JSON Swagger ファイルにエクスポートするには、次の GET リクエストを送信します。

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1 Accept: application/json 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

ドキュメントと、統合およびオーソライザーの詳細を含む API エンティティ定義を YAML Swagger ファイルにエクスポートするには、次の GET リクエストを送信します。

Copy
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1 Accept: application/yaml 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

API Gateway コンソールを使用して、API の発行されたドキュメントをエクスポートおよびダウロードするには、「API Gateway コンソールを使用した API のエクスポート」の手順に従います。