# 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) コレクションを使用してすべてのドキュメントバージョンを維持します。