ドキュメントスナップショットの作成と API ステージへの関連付けドキュメントスナップショットの作成ドキュメントスナップショットの更新ドキュメントスナップショットの取得 API ステージへのドキュメントスナップショットの関連付けステージに関連付けられたドキュメントスナップショットのダウンロード

API Gateway REST API を使用した API ドキュメントを公開する

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

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

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


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"
}

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

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

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

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


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"
}

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

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

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


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."
    }]
}

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

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

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


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 プロパティに必要なドキュメントバージョンを設定します。


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 コンソール、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 OpenAPI ファイルに API ドキュメントをエクスポートするには、次の GET リクエストを送信します。


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 エンティティ定義に OpenAPI によりサポートされているドキュメントプロパティが含まれています。この出力には、統合や Lambda オーソライザー (以前のカスタムオーソライザー) の詳細は含まれません。両方の詳細を含めるには、extensions=integrations,authorizers,documentation を設定します。オーソライザーの詳細は含めず統合の詳細を含めるには、extensions=integrations,documentation を設定します。

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

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

OpenAPI 3.0


{
   "openapi": "3.0.0",
   "info": {
      "description": "API info description",
      "version": "2016-11-22T22:39:14Z",
      "title": "doc",
      "x-bar": "API info x-bar"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            },
            "x-example": "x- Method example"
         },
         "x-bar": "resource x-bar"
      }
   },
   "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",
   "servers": [
      {
         "url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}

OpenAPI 2.0


{
  "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 マップで定義された OpenAPI に準拠する属性の場合、API Gateway は関連付けられた API エンティティ定義に属性を挿入します。x-something の属性は、標準 OpenAPI 拡張です。この拡張は、API エンティティ定義に伝達されます。たとえば、x-example メソッドの GET 属性を参照してください。foo などの属性は、OpenAPI 仕様の一部ではないため、関連付けられた API エンティティ定義には挿入されません。

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

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


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 OpenAPI ファイルにエクスポートするには、次の GET リクエストを送信します。


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 コンソールを使用して REST API をエクスポートする」の手順に従います。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

API Gateway REST API を使用して API を文書化する

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