# API Gateway での REST API のドキュメント 顧客が API について理解して使いやすくするため、API をドキュメント化してください。API をドキュメント化しやすいように、API Gateway では API 開発プロセスの不可欠な部分として個々の API エンティティのヘルプコンテンツを追加および更新できます。API Gateway にはソースコンテンツが保存され、さまざまなバージョンのドキュメントをアーカイブできます。ドキュメントバージョンと API ステージを関連付けたり、ステージ固有のドキュメントスナップショットを外部 OpenAPI ファイルにエクスポートしたり、ファイルをドキュメントの出版物として配布したりすることができます。 API をドキュメント化するには、[API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/) を呼び出すか、[AWS SDK](https://aws.amazon.com/developer/tools/) のいずれかを使用するか、API Gateway 用の [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/) を使用するか、API Gateway コンソールを使用できます。加えて、外部 OpenAPI ファイルで定義されたドキュメントパーツをインポートまたはエクスポートすることができます。 API ドキュメントをデベロッパーと共有するには、デベロッパーポータルを使用できます。例については、AWS パートナーネットワーク (APN) ブログの「[Developer Hub を最新の状態に保つための ReadMe と API Gateway の統合](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/)」または「[SmartBear の SwaggerHub を使用して Amazon API Gateway での API 開発を効率化する方法](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/)」を参照してください。 **Topics** + [API Gateway での API ドキュメントの表現](api-gateway-documenting-api-content-representation.md) + [API Gateway コンソールを使用して API を文書化する](api-gateway-documenting-api-quick-start-with-console.md) + [API Gateway コンソールを使用して API ドキュメントを公開する](apigateway-documenting-api-with-console.md) + [API Gateway REST API を使用して API を文書化する](api-gateway-documenting-api-quick-start-with-restapi.md) + [API Gateway REST API を使用した API ドキュメントを公開する](api-gateway-documenting-api-quick-start-publishing.md) + [API ドキュメントのインポート](api-gateway-documenting-api-quick-start-import-export.md) + [API Gateway で API ドキュメントへのアクセスを制御する](api-gateway-documenting-api-content-provision-and-consumption.md) # API Gateway での API ドキュメントの表現 API Gateway API ドキュメントは、API、リソース、メソッド、リクエスト、レスポンス、メッセージパラメータ (つまり、パス、クエリ、ヘッダー) と、オーソライザーおよびモデルを含む特定の API エンティティと関連付けられた個々のドキュメントパートで構成されます。 API Gateway では、ドキュメントパートは [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースにより表現されます。API ドキュメント全体は、[DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html) コレクションとして表現されます。 API をドキュメント化するには、`DocumentationPart` インスタンスを作成して `DocumentationParts` コレクションに追加し、API の展開に応じてドキュメントパーツのバージョンを維持することが必要です。 **Topics** + [ドキュメントパーツ](#api-gateway-documenting-api-content-representation-documentation-parts) + [ドキュメントバージョン](#api-gateway-documenting-api-content-representation-documentation-versions) ## ドキュメントパーツ [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースは、個々の API エンティティに適用されるドキュメントコンテンツが保存される JSON オブジェクトです。これには、ドキュメントの UTF-8 コンテンツとすべての主要なローカライゼーション言語が含まれます。その `properties` フィールドには、ドキュメントコンテンツがキー/値ペアのマップとして含まれています。その `location` プロパティは、関連付けられた API エンティティを識別します。 コンテンツマップのシェイプは、API デベロッパーであるお客様が決定します。キー/値ペアの値は、文字列、数値、ブール値、オブジェクト、配列のいずれかです。`location` オブジェクトのシェイプは、ターゲットとなるエンティティタイプによって異なります。 `DocumentationPart` リソースでは、コンテンツの継承がサポートされます。API エンティティのドキュメントコンテンツは、その API エンティティの子に適用されます。子エンティティとコンテンツ継承の定義の詳細については、「[より一般的な仕様の API エンティティからのコンテンツの継承](#api-gateway-documenting-api-content-inheritance)」を参照してください。 ### ドキュメントパーツの場所 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) インスタンスの [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) プロパティは、関連付けられたコンテンツが適用される API エンティティを識別します。API エンティティは、[RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)、[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)、[Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)、[MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)、[Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html)、[Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) などの API Gateway REST API リソースです。エンティティは、URL パスパラメーター、クエリ文字列パラメーター、リクエストまたはレスポンスヘッダーパラメーター、リクエストまたはレスポンス本部、レスポンスステータスコードなどのメッセージパラメーターでもかまいません。 API エンティティを指定するには、`location` オブジェクトの [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) 属性を `API`、`AUTHORIZER`、`MODEL`、`RESOURCE`、`METHOD`、`PATH_PARAMETER`、`QUERY_PARAMETER`、`REQUEST_HEADER`、`REQUEST_BODY`、`RESPONSE`、`RESPONSE_HEADER`、`RESPONSE_BODY` のいずれかに設定します。 API エンティティの `type` によっては、[method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method)、[name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name)、[path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path)、[statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode) などの他の `location` 属性を指定する必要があります。これらのすべての属性が特定の API エンティティで有効なわけではありません。たとえば、`type`, `path`、`name`、`statusCode` は `RESPONSE` エンティティの有効な属性です。`type` エンティティの有効な location 属性は `path` と `RESOURCE` だけです。特定の API エンティティの `location` の `DocumentationPart` に無効なフィールドを含めるとエラーになります。 有効な `location` フィールドがすべて必須なわけではありません。たとえば、`type` は、すべての API エンティティで有効かつ必須の `location` フィールドです。一方、`method`、`path`、`statusCode` は、`RESPONSE` エンティティで有効ですが、必須の属性ではありません。明示的に指定されていない場合、有効な `location` フィールドではそのデフォルト値が使用されます。`path` のデフォルト値は `/`、つまり API のルートリソースです。`method` または `statusCode` のデフォルト値は `*` です。これは、ぞれぞれ任意のメソッドまたはステータスコードを意味します。 ### ドキュメントパーツのコンテンツ `properties` 値は、JSON 文字列としてエンコードされます。`properties` 値には、ドキュメント要件を満たすために選択した情報がすべて含まれます。たとえば、有効なコンテンツマップを以下に示します。 ``` { "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." } ``` API Gateway は任意の有効な JSON 文字列をコンテンツマップとして受け入れますが、コンテンツ属性は 2 つのカテゴリ (OpenAPI が認識できるカテゴリと認識できないカテゴリ) として扱われます。前の例では、`info`、`description`、`x-custom-info` が OpenAPI により標準の OpenAPI オブジェクト、プロパティ、または拡張として認識されます。一方、`my-info` は OpenAPI 仕様に準拠していません。API Gateway は、OpenAPI 準拠のコンテンツ属性を、関連付けられた `DocumentationPart` インスタンスから API エンティティ定義に伝達します。API Gateway は、非準拠のコンテンツ属性を API エンティティ定義に伝達しません。 別の例として、`DocumentationPart` エンティティのターゲットとなった `Resource` を示します。 ``` { "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } } ``` ここでは、`type` と `path` の両方が `RESOURCE` タイプを識別するための有効なフィールドです。ルートリソース (`/`) では、`path` フィールドを省略できます。 ``` { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } } ``` これは、次の `DocumentationPart` インスタンスと同じです。 ``` { "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } } ``` ### より一般的な仕様の API エンティティからのコンテンツの継承 オプションの `location` フィールドのデフォルト値では、API エンティティのパターン化された説明が提供されます。`location` オブジェクトでデフォルト値を使用すると、`properties` マップ内の全般的な説明を、このタイプの `DocumentationPart` パターンを持つ `location` インスタンスに追加できます。API Gateway は、汎用 API エンティティの `DocumentationPart` から該当する OpenAPI ドキュメント属性を抽出し、一般的な `location` パターンに一致するか、正確な値に一致する `location` フィールドを持つ特定の API エンティティに挿入します。ただし、特定のエンティティに `DocumentationPart` インスタンスが既に関連付けられている場合を除きます。この動作は、より全般的な仕様の API エンティティからのコンテンツ継承とも呼ばれます。 コンテンツ継承は、特定の API エンティティのタイプには適用されません。詳細については以下の表を参照してください。 API エンティティが複数の `DocumentationPart` の位置パターンに一致する場合、そのエンティティは優先度と具体性が最も高い位置フィールドを持つドキュメントパーツを継承します。優先順位は、`path`、`statusCode` の順です。`path` フィールドと一致させるため、API Gateway は最も具体的なパス値を持つエンティティを選択します。次の表に、いくつかの例とともにこれを示します。 | ケース | `path` | `statusCode` | `name` | 解説 | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | id | この位置パターンに関連付けられたドキュメントは、位置パターンに一致するエンティティによって継承されます。 | | 2 | /pets | 200 | id | この位置パターンに関連付けられたドキュメントは、ケース 1 とケース 2 の両方が一致する場合に位置パターンに一致するエンティティによって継承されます。ケース 2 の方がケース 1 より具体的だからです。 | | 3 | /pets/petId | \$1 | id | この位置パターンに関連付けられたドキュメントは、ケース 1、2、および 3 が一致する場合に位置パターンに一致するエンティティによって継承されます。ケース 3 の方がケース 2 より優先度が高く、ケース 1 より具体的だからです。 | ここでは、汎用的な `DocumentationPart` インスタンスと具体的なインスタンスの違いを別の例で示します。上書きされていない限り、全般的なエラーメッセージ `"Invalid request error"` が `400` エラーレスポンスの OpenAPI 定義に挿入されます。 ``` { "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" } ``` 次のように上書きすると、`400` リソースでのすべてのメソッドに対する `/pets` レスポンスに、説明 `"Invalid petId specified"` が代わりに挿入されます。 ``` { "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" } ``` ### `DocumentationPart` の有効な位置フィールド 次の表に、特定のタイプの API エンティティに関連付けられた [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースの有効なフィールド、必須のフィールド、および適用可能なデフォルト値を示します。 | API エンティティ | 有効な位置フィールド | 必須の位置フィールド | デフォルトフィールド値 | 継承可能なコンテンツ | | --- | --- | --- | --- | --- | | [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html): | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | 該当なし | いいえ | | [リソース](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | path の初期値は です。/ | いいえ | | [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path と method のデフォルト値は、それぞれ / と \$1 です。 | はい。プレフィックスにより path に一致し、任意の値の method に一致します。 | | クエリパラメーター | 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
| type | path と method のデフォルト値は、それぞれ / と \$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method に一致します。 | | リクエストボディ | 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path と method のデフォルト値は、それぞれ / と \$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method に一致します。 | | リクエストヘッダーパラメーター | 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path と method のデフォルト値は、それぞれ / と \$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method に一致します。 | | リクエストパスパラメーター | 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
| type, name | path と method のデフォルト値は、それぞれ / と \$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method に一致します。 | | レスポンス | 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path、method、statusCode のデフォルト値は、それぞれ /、\$1、\$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method と statusCode に一致します。 | | レスポンスヘッダー | 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path、method、statusCode のデフォルト値は、それぞれ /、\$1、\$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method と statusCode に一致します。 | | レスポンス本文 | 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path、method、statusCode のデフォルト値は、それぞれ /、\$1、\$1 です。 | はい。プレフィックスにより path に一致し、正確な値により method と statusCode に一致します。 | | [オーソライザー](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | 該当なし | いいえ | | [モデル](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | 該当なし | いいえ | ## ドキュメントバージョン ドキュメントバージョンは、API の [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) コレクションのスナップショットであり、バージョン識別子でタグ付けされます。API のドキュメントを発行するには、ドキュメントバージョンを作成して API ステージに関連付け、そのステージ固有のバージョンの API ドキュメントを外部 OpenAPI ファイルにエクスポートします。API Gateway では、ドキュメントスナップショットが [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) リソースとして表現されます。 API を更新するとき、新しいバージョンの API を作成します。API Gateway では、[DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) コレクションを使用してすべてのドキュメントバージョンを維持します。 # API Gateway コンソールを使用して API を文書化する このセクションでは、API Gateway コンソールを使用して API のドキュメントパートを作成および維持する方法について説明します。 API のドキュメントを作成および編集するための前提条件は、すでに API を作成していることです。このセクションでは、例として [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API を使用します。API Gateway コンソールを使用して API を作成するには、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」の手順に従います。 **Topics** + [`API` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-api-entity-with-console) + [`RESOURCE` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-resource-entity-with-console) + [`METHOD` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-method-entity-with-console) + [`QUERY_PARAMETER` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console) + [`PATH_PARAMETER` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console) + [`REQUEST_HEADER` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console) + [`REQUEST_BODY` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console) + [`RESPONSE` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-response-with-console) + [`RESPONSE_HEADER` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console) + [`RESPONSE_BODY` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console) + [`MODEL` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-model-entity-with-console) + [`AUTHORIZER` エンティティのドキュメント化](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console) ## `API` エンティティのドキュメント化 `API` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[API]** を選択します。 `API` のドキュメントパーツが作成されなかった場合、ドキュメントパーツの `properties` マップエディターを取得します。テキストエディタに次の `properties` マップを入力します。 ``` { "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } } ``` **注記** `properties` マップを JSON 文字列にエンコードする必要はありません。API Gateway コンソールにより、JSON オブジェクトが自動的に stringify されます。 1. **[ドキュメントパーツの作成]** を選択します。 **[リソース]** ペインに `API` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで、**[リソース]** を選択します。 1. **[API アクション]** メニューを選択し、**[API ドキュメントの更新]** を選択します。 ![\[API Gateway コンソールで API エンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png) 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. API の名前を選択し、API カードで **[編集]** を選択します。 ## `RESOURCE` エンティティのドキュメント化 `RESOURCE` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[リソース]** を選択します。 1. **[パス]** にはパスを入力します。 1. テキストエディタに説明を入力します。例: ``` { "description": "The PetStore's root resource." } ``` 1. **[ドキュメントパーツの作成]** を選択します。リストにないリソースのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 **[リソース]** ペインに `RESOURCE` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで、**[リソース]** を選択します。 1. リソースを選択し、**[ドキュメントの更新]** を選択します。 ![\[API Gateway コンソールでリソースエンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png) 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. ドキュメントパーツを含むリソースを選択し、**[編集]** を選択します。 ## `METHOD` エンティティのドキュメント化 `METHOD` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[メソッド]** を選択します。 1. **[パス]** にはパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. テキストエディタに説明を入力します。例: ``` { "tags" : [ "pets" ], "summary" : "List all pets" } ``` 1. **[ドキュメントパーツの作成]** を選択します。リストにないメソッドのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 **[リソース]** ペインに `METHOD` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで、**[リソース]** を選択します。 1. メソッドを選択し、**[ドキュメントの更新]** を選択します。 ![\[API Gateway コンソールでメソッドエンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png) 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. メソッドを選択するか、メソッドを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `QUERY_PARAMETER` エンティティのドキュメント化 `QUERY_PARAMETER` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[クエリパラメータ]** を選択します。 1. **[パス]** にはパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[名前]** に名前を入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないクエリパラメータのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. クエリパラメータを選択するか、クエリパラメータを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `PATH_PARAMETER` エンティティのドキュメント化 `PATH_PARAMETER` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[パスパラメータ]** を選択します。 1. **[パス]** にはパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[名前]** に名前を入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないパスパラメータのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. パスパラメータを選択するか、パスパラメータを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `REQUEST_HEADER` エンティティのドキュメント化 `REQUEST_HEADER` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[リクエストヘッダー]** を選択します。 1. **[パス]** には、リクエストヘッダーのパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[名前]** に名前を入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないリクエストヘッダーのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. リクエストヘッダーを選択するか、リクエストヘッダーを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `REQUEST_BODY` エンティティのドキュメント化 `REQUEST_BODY` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[リクエスト本文]** を選択します。 1. **[パス]** には、リクエスト本文のパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないリクエスト本文のドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. リクエスト本文を選択するか、リクエスト本文を含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `RESPONSE` エンティティのドキュメント化 `RESPONSE` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には、**[レスポンス (ステータスコード)]** を選択します。 1. **[パス]** には、レスポンスのパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[ステータスコード]** には、HTTP ステータスコードを入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないレスポンスステータスコードのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. レスポンスステータスコードを選択するか、レスポンスステータスコードを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `RESPONSE_HEADER` エンティティのドキュメント化 `RESPONSE_HEADER` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[レスポンスヘッダー]** を選択します。 1. **[パス]** には、レスポンスヘッダーのパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[ステータスコード]** には、HTTP ステータスコードを入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないレスポンスヘッダーのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. レスポンスヘッダーを選択するか、レスポンスヘッダーを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `RESPONSE_BODY` エンティティのドキュメント化 `RESPONSE_BODY` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[レスポンス本文]** を選択します。 1. **[パス]** には、レスポンス本文のパスを入力します。 1. **[メソッド]** で、HTTP 動詞を選択します。 1. **[ステータスコード]** には、HTTP ステータスコードを入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないレスポンス本文のドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで、**[リソースとメソッド]** タブを選択します。 1. レスポンス本文を選択するか、レスポンス本文を含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。 1. **[編集]** を選択します。 ## `MODEL` エンティティのドキュメント化 `MODEL` エンティティをドキュメント化するには、モデルの `DocumentPart` インスタンスと、モデルの各 `properties`' を作成および管理する必要があります。たとえば、各 API に付属する `Error` モデルには、デフォルトでスキーマ定義 ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` があり、2 つの `DocumentationPart` インスタンス (1 つは `Model` 用、もう 1 つはその `message` プロパティ用) が必要です。 ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` および ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` API がエクスポートされると、`DocumentationPart` のプロパティにより元のスキーマの値が上書きされます。 `MODEL` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[モデル]** を選択します。 1. **[名前]** に、モデルの名前を入力します。 1. テキストエディタに説明を入力します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないモデルのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のモデルにドキュメントパーツを追加するか、編集します。 **[モデル]** ペインに `MODEL` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. ナビゲーションペインで、**[モデル]** を選択します。 1. モデルを選択し、**[ドキュメントの更新]** を選択します。 ![\[API Gateway コンソールでモデルエンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png) 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで **[モデル]** タブを選択します。 1. 検索バーを使用するかモデルを選択し、**[編集]** を選択します。 ## `AUTHORIZER` エンティティのドキュメント化 `AUTHORIZER` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。 1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。 1. **[ドキュメントタイプ]** には **[オーソライザー]** を選択します。 1. **[名前]** に、オーソライザーの名前を入力します。 1. テキストエディタに説明を入力します。オーソライザーの有効な [`location`] フィールドで値を指定します。 1. **[ドキュメントパーツの作成]** を選択します。リストにないオーソライザーのドキュメントを作成できます。 1. 必要に応じて、これらのステップを繰り返し、他のオーソライザーにドキュメントパーツを追加するか、編集します。 既存のドキュメントパーツを編集するには、以下を実行します。 1. **[ドキュメント]** ペインで **[オーソライザー]** タブを選択します。 1. 検索バーを使用するかオーソライザーを選択し、**[編集]** を選択します。 # API Gateway コンソールを使用して API ドキュメントを公開する 次の手順では、ドキュメントバージョンを発行する方法について説明します。 **API Gateway コンソールを使用してドキュメントバージョンを公開するには** 1. メインナビゲーションペインで、**[ドキュメント]** を選択します。 1. **[ドキュメントの発行]** を選択します。 1. 出版物をセットアップします。 1. **[ステージ]** では、ステージを選択します。 1. **[バージョン]** には、バージョン識別子を入力します (例: `1.0.0`)。 1. (オプション) **[説明]** に説明を入力します。 1. [**Publish**] を選択します。 これで、ドキュメントを OpenAPI ファイルにエクスポートすることにより、発行されたドキュメントのダウンロードに進むことができるようになります。詳細については、「[API Gateway から REST API をエクスポートする](api-gateway-export-api.md)」を参照してください。 # API Gateway REST API を使用して API を文書化する このセクションでは、API Gateway REST API を使用して API のドキュメントパートを作成および維持する方法について説明します。 API のドキュメントを作成および編集する前に、まず API を作成します。このセクションでは、例として [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API を使用します。API Gateway コンソールを使用して API を作成するには、「[チュートリアル: サンプルをインポートして REST API を作成する](api-gateway-create-api-from-example.md)」の手順に従います。 **Topics** + [`API` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api) + [`RESOURCE` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource) + [`METHOD` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method) + [`QUERY_PARAMETER` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter) + [`PATH_PARAMETER` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter) + [`REQUEST_BODY` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body) + [`REQUEST_HEADER` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header) + [`RESPONSE` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response) + [`RESPONSE_HEADER` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header) + [`AUTHORIZER` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer) + [`MODEL` エンティティのドキュメント化](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model) + [ドキュメントパーツの更新](#api-gateway-documenting-api-quick-start-with-restapi-update-content) + [ドキュメントパーツの一覧表示](#api-gateway-documenting-api-quick-start-with-restapi-list-parts) ## `API` エンティティのドキュメント化 [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) のドキュメントを追加するには、API エンティティの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { ... "id": "s2e5xf", "location": { "path": null, "method": null, "name": null, "statusCode": null, "type": "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` ドキュメントパートが既に追加されている場合、エラーメッセージ `409 Conflict` を含む `Documentation part already exists for the specified location: type 'API'."` レスポンスが返されます。この場合、[documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) オペレーションを呼び出す必要があります。 ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] } ``` 正常なレスポンスでは、更新された `200 OK` インスタンスをペイロードに含む `DocumentationPart` ステータスコードが返されます。 ## `RESOURCE` エンティティのドキュメント化 API のルートリソースのドキュメントを追加するには、対応する [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) リソースをターゲットとした [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" } }, "id": "p76vqo", "location": { "path": "/", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` リソースパスが指定されていない場合、リソースはルートリソースとみなされます。`"path": "/"` を `properties` に追加すると、明示的に指定できます。 API の子リソースのドキュメントを作成するには、対応する [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) リソースをターゲットとした [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" } }, "id": "qcht86", "location": { "path": "/pets", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` パスパラメータにより指定された子リソースのドキュメントを追加するには、[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) リソースをターゲットとした [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" } }, "id": "k6fpwb", "location": { "path": "/pets/{petId}", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` **注記** `RESOURCE` エンティティの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) インスタンスは、どの子リソースも継承することができません。 ## `METHOD` エンティティのドキュメント化 API のメソッドのドキュメントを追加するには、対応する [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) リソースをターゲットとした [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 前のリクエストで `location.method` フィールドが指定されていない場合、ワイルドカード文字 `ANY` で表される `*` であるとみなされます。 `METHOD` エンティティのドキュメントのコンテンツを更新するには、新しい `properties` マップを指定して [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) オペレーションを呼び出します。 ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] } ``` 正常なレスポンスでは、更新された `200 OK` インスタンスをペイロードに含む `DocumentationPart` ステータスコードが返されます。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ``` ## `QUERY_PARAMETER` エンティティのドキュメント化 リクエストクエリパラメータのドキュメントを追加するには、`QUERY_PARAMETER` タイプをターゲットとした、有効なフィールド `path` および `name` を含む [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" } }, "id": "h9ht5w", "location": { "path": "/pets", "method": "GET", "name": "page", "statusCode": null, "type": "QUERY_PARAMETER" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` `properties` エンティティのドキュメントパーツの `QUERY_PARAMETER` マップは、いずれかの子 `QUERY_PARAMETER` エンティティが継承できます。たとえば、`treats` の後に `/pets/{petId}` リソースを追加して、`GET` で `/pets/{petId}/treats` メソッドを有効にし、`page` クエリパラメータを開示した場合、この子クエリパラメータは `DocumentationPart` メソッドの同様の名前のクエリパラメータから `properties` の `GET /pets` マップを継承します。ただし、`DocumentationPart` メソッドの `page` クエリパラメータに `GET /pets/{petId}/treats` リソースを明示的に追加した場合を除きます。 ## `PATH_PARAMETER` エンティティのドキュメント化 パスパラメータのドキュメントを追加するには、`PATH_PARAMETER` エンティティの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" } }, "id": "ckpgog", "location": { "path": "/pets/{petId}", "method": "*", "name": "petId", "statusCode": null, "type": "PATH_PARAMETER" }, "properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}" } ``` ## `REQUEST_BODY` エンティティのドキュメント化 リクエストボディのドキュメントを追加するには、リクエストボディの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" } }, "id": "kgmfr1", "location": { "path": "/pets", "method": "POST", "name": null, "statusCode": null, "type": "REQUEST_BODY" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` ## `REQUEST_HEADER` エンティティのドキュメント化 リクエストヘッダーのドキュメントを追加するには、リクエストヘッダーの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "REQUEST_HEADER", "path" : "/pets", "method" : "GET", "name" : "x-my-token" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" } }, "id": "h0m3uf", "location": { "path": "/pets", "method": "GET", "name": "x-my-token", "statusCode": null, "type": "REQUEST_HEADER" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` ## `RESPONSE` エンティティのドキュメント化 ステータスコードのレスポンスのドキュメントを追加するには、対応する [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) リソースをターゲットとする [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" } }, "id": "lattew", "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` ## `RESPONSE_HEADER` エンティティのドキュメント化 レスポンスヘッダーのドキュメントを追加するには、レスポンスヘッダーの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" } }, "id": "fev7j7", "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" } ``` この `Content-Type` レスポンスヘッダーのドキュメントは、API の任意のレスポンスの `Content-Type` ヘッダーのデフォルトドキュメントです。 ## `AUTHORIZER` エンティティのドキュメント化 API オーソライザーのドキュメントを追加するには、指定されたオーソライザーをターゲットとする [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" } }, "id": "pw3qw3", "location": { "path": null, "method": null, "name": "myAuthorizer", "statusCode": null, "type": "AUTHORIZER" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` **注記** `AUTHORIZER` エンティティの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) インスタンスは、どの子リソースも継承することができません。 ## `MODEL` エンティティのドキュメント化 `MODEL` エンティティをドキュメント化するには、モデルの `DocumentPart` インスタンスと、モデルの各 `properties`' を作成および管理する必要があります。たとえば、各 API に付属する `Error` モデルには、デフォルトでスキーマ定義 ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` があり、2 つの `DocumentationPart` インスタンス (1 つは `Model` 用、もう 1 つはその `message` プロパティ用) が必要です。 ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` および ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` API がエクスポートされると、`DocumentationPart` のプロパティにより元のスキーマの値が上書きされます。 API モデルのドキュメントを追加するには、指定されたモデルをターゲットとする [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) リソースを追加します。 ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` 成功した場合、オペレーションは新しく作成された `201 Created` インスタンスをペイロードに含む、`DocumentationPart` レスポンスを返します。例: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" } }, "id": "lkn4uq", "location": { "path": null, "method": null, "name": "Pet", "statusCode": null, "type": "MODEL" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` 同じステップを繰り返して、いずれかのモデルのプロパティの DocumentationPart インスタンスを作成します。 **注記** `MODEL` エンティティの [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) インスタンスは、どの子リソースも継承することができません。 ## ドキュメントパーツの更新 任意のタイプの API エンティティのドキュメントパートを更新するには、指定されたパート識別子の [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) インスタンスで PATCH リクエストを送信し、既存の `properties` マップを新しいマップに置き換えます。 ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "RESOURCE_PATH", "value" : "NEW_properties_VALUE_AS_JSON_STRING" } ] } ``` 正常なレスポンスでは、更新された `200 OK` インスタンスをペイロードに含む `DocumentationPart` ステータスコードが返されます。 複数のドキュメントパーツを 1 回の `PATCH` リクエストで更新できます。 ## ドキュメントパーツの一覧表示 任意のタイプの API エンティティのドキュメントパートを一覧表示するには、[DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) コレクションで GET リクエストを送信します。 ``` GET /restapis/restapi_id/documentation/parts 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 ``` 正常なレスポンスでは、利用可能な `200 OK` インスタンスをペイロードに含む `DocumentationPart` ステータスコードが返されます。 # 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)」の手順に従います。 # API ドキュメントのインポート API エンティティ定義のインポートと同様、ドキュメントパートは API Gateway で外部 OpenAPI ファイルから API にインポートできます。インポートするドキュメントパートは、有効な OpenAPI 定義ファイルの [x-amazon-apigateway-documentation オブジェクト](api-gateway-swagger-extensions-documentation.md) 拡張内で指定します。ドキュメントをインポートしても、既存の API エンティティ定義は変更されません。 API Gateway で新しく指定されたドキュメントパートを既存のドキュメントパートにマージしたり、既存のドキュメントパートを上書きしたりするオプションがあります。`MERGE` モードでは、OpenAPI ファイルで定義された新しいドキュメントパーツが API の `DocumentationParts` コレクションに追加されます。インポートする `DocumentationPart` がすでに存在する場合、2 つの属性が異なる場合はインポートされた属性によって既存の属性が置き換えられます。他の既存のドキュメント属性は影響を受けません。`OVERWRITE` モードでは、インポートされた OpenAPI 定義ファイルに従って `DocumentationParts` コレクション全体が置き換えられます。 ## API Gateway REST API を使用してドキュメントパートをインポートする API Gateway REST API を使用して API ドキュメントをインポートするには、[documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html) オペレーションを呼び出します。次の例は、API の既存のドキュメントパーツを単一の `GET / ` メソッドに置き換えて、成功時は `200 OK` レスポンスを返す方法を示しています。 ------ #### [ OpenAPI 3.0 ] ``` PUT /restapis//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//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](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) または [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html) を呼び出すこともできます。API インポートからドキュメントパーツを除外するには、リクエストクエリパラメータで `ignore=documentation` を設定します。 ## API Gateway コンソールを使用してドキュメントパートをインポートする 次の手順では、ドキュメントパーツをインポートする方法について説明します。 **コンソールを使用して API のドキュメントパーツを外部ファイルからインポートするには** 1. メインナビゲーションペインで、**[ドキュメント]** を選択します。 1. [**インポート**] を選択します。 1. 既存のドキュメントがある場合は、新しいドキュメントを **[上書き]** するか **[マージ]** するかを選択します。 1. **[ファイルの選択]** を選択してドライブからファイルをロードするか、ファイルのコンテンツをファイルビューに入力します。例として、「[API Gateway REST API を使用してドキュメントパートをインポートする](#api-gateway-importing-api-with-swagger-file-using-rest-api)」にあるサンプルリクエストのペイロードを参照してください。 1. インポート時の警告の処理方法を選択します。**[警告を失敗とみなす]** または **[警告を無視する]** を選択します。詳細については、「[API Gateway への API のインポートによるエラーと警告](api-gateway-import-api-errors-warnings.md)」を参照してください。 1. [**インポート**] を選択します。 # API Gateway で API ドキュメントへのアクセスを制御する API ドキュメントの執筆と編集を行う専用ドキュメントチームを持っている場合、デベロッパー (API 開発用) と執筆者および編集者 (コンテンツ開発用) に別個のアクセス権限を設定することができます。これは特に、サードパーティベンダーがドキュメントの作成に関与している場合に適しています。 API ドキュメントを作成、更新、発行するアクセス許可をドキュメントチームに付与するには、次の IAM ポリシーを持つ IAM ロールをドキュメントチームに割り当てることができます。ここで、*account\$1id* はドキュメントチームの AWS アカウント ID です。 ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StmtDocPartsAddEditViewDelete", "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*" ] } ] } ``` ------ API Gateway リソースにアクセスするためのアクセス許可の設定については、「[Amazon API Gateway と IAM の連携方法](security_iam_service-with-iam.md)」を参照してください。