# API Gateway REST API を使用した API ドキュメントを公開する
API のドキュメントを発行するには、ドキュメントスナップショットを作成、更新、または取得した後、ドキュメントスナップショットを API ステージに関連付けます。ドキュメントスナップショットを作成するとき、同時に API ステージに関連付けることもできます。
**Topics**
+ [ドキュメントスナップショットの作成と API ステージへの関連付け](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [ドキュメントスナップショットの作成](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [ドキュメントスナップショットの更新](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [ドキュメントスナップショットの取得](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [API ステージへのドキュメントスナップショットの関連付け](#api-gateway-documenting-api-publishing-stage-association)
+ [ステージに関連付けられたドキュメントスナップショットのダウンロード](#api-gateway-documenting-api-publishing-export-documentation-version)
## ドキュメントスナップショットの作成と 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](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html) を呼び出し、指定した API ステージにスナップショットを関連付けることもできます。既存のドキュメントスナップショットの更新またはクエリを実行してから、そのステージの関連付けを更新することもできます。次の 4 つのセクションでは、そのステップを示します。
## ドキュメントスナップショットの作成
API のドキュメントパートのスナップショットを作成するには、新しい [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) リソースを作成し、API の [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) コレクションに追加します。
```
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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) リソースの `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](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) リソースに対して `GET` リクエストを送信します。次の例は、特定のバージョン識別子 1.0.0 のドキュメントスナップショットを取得する方法を示しています。
```
GET /restapis//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](https://docs.aws.amazon.com/apigateway/latest/api/) を使用してドキュメントスナップショットを API ステージに関連付けるには、[stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) オペレーションを呼び出して `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](https://swagger.io/tools/swagger-ui/) など) が API エンティティ定義を解析してドキュメント属性を抽出する場合、`properties` インスタンスの OpenAPI に準拠していない `DocumentationPart` 属性はどれもツールで使用できません。一方、ドキュメントレンダリングツールが `x-amazon-apigateway-documentation` オブジェクトを解析してコンテンツを取得するか、ツールが [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) および [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) を呼び出して 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 をエクスポートする](api-gateway-export-api.md#api-gateway-export-api-from-console)」の手順に従います。