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

API Gateway での API ドキュメントの表現

API Gateway API ドキュメントは、API、リソース、メソッド、リクエスト、レスポンス、メッセージパラメーター (つまり、パス、クエリ、ヘッダー) と、オーソライザーおよびモデルを含む特定の API エンティティと関連付けられた個々のドキュメントパーツで構成されます。

API Gateway では、ドキュメントパーツは DocumentationPart リソースにより表現されます。API ドキュメント全体は、DocumentationParts コレクションとして表現されます。

API をドキュメント化するには、DocumentationPart インスタンスを作成して DocumentationParts コレクションに追加し、API の展開に応じてドキュメントパーツのバージョンを維持することが必要です。

ドキュメントパーツ

DocumentationPart リソースは、個々の API エンティティに適用されるドキュメントコンテンツが保存される JSON オブジェクトです。その properties フィールドには、ドキュメントコンテンツがキー/値ペアのマップとして含まれています。その location プロパティは、関連付けられた API エンティティを識別します。

コンテンツマップのシェイプは、API 開発者であるお客様が決定します。キー/値ペアの値は、文字列、数値、ブール値、オブジェクト、配列のいずれかです。location オブジェクトのシェイプは、ターゲットとなるエンティティタイプによって異なります。

DocumentationPart リソースでは、コンテンツの継承がサポートされます。API エンティティのドキュメントコンテンツは、その API エンティティの子に適用されます。子エンティティとコンテンツ継承の定義の詳細については、「より一般的な仕様の API エンティティからのコンテンツの継承」を参照してください。

ドキュメントパーツの場所

DocumentationPart インスタンスの location プロパティは、関連付けられたコンテンツが適用される API エンティティを識別します。API エンティティは、RestApiResourceMethodMethodResponseAuthorizerModel などの API Gateway REST API リソースです。エンティティは、URL パスパラメーター、クエリ文字列パラメーター、リクエストまたはレスポンスヘッダーパラメーター、リクエストまたはレスポンス本部、レスポンスステータスコードなどのメッセージパラメーターでもかまいません。

API エンティティを指定するには、location オブジェクトの type 属性を APIAUTHORIZERMODELRESOURCEMETHODPATH_PARAMETERQUERY_PARAMETERREQUEST_HEADERREQUEST_BODYRESPONSERESPONSE_HEADERRESPONSE_BODY のいずれかに設定します。

API エンティティの type によっては、methodnamepathstatusCode などの他の location 属性を指定する必要があります。これらのすべての属性が特定の API エンティティで有効なわけではありません。たとえば、type, pathnamestatusCodeRESPONSE エンティティの有効な属性です。RESOURCE エンティティの有効な location 属性は typepath だけです。特定の API エンティティの DocumentationPartlocation に無効なフィールドを含めるとエラーになります。

有効な location フィールドがすべて必須なわけではありません。たとえば、type は、すべての API エンティティで有効かつ必須の location フィールドです。一方、methodpathstatusCode は、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 Swagger.", "my-info" : "My custom info not recognized by Swagger." }

API Gateway REST API を使用して properties の値として設定するには、このオブジェクトを JSON 文字列 としてエンコードします。

"{\n\t\"info\": {\n\t\t\"description\": \"My first API with Amazon API Gateway.\"\n\t}, … \n}"

API Gateway は任意の JSON 文字列をコンテンツマップとして受け入れますが、コンテンツ属性は 2 つのカテゴリ (Swagger が認識できるカテゴリと認識できないカテゴリ) として扱われます。前の例では、infodescriptionx-custom-info が Swagger により標準の Swagger オブジェクト、プロパティ、または拡張として認識されます。一方、my-info は Swagger 仕様に準拠していません。API Gateway は、Swagger 準拠のコンテンツ属性を、関連付けられた DocumentationPart インスタンスから API エンティティ定義に伝達します。API Gateway は、非準拠のコンテンツ属性を API エンティティ定義に伝達しません。

別の例として、Resource エンティティのターゲットとなった DocumentationPart を示します。

{ "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } }

ここでは、typepath の両方が 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 マップ内の全般的な説明を、このタイプの location パターンを持つ DocumentationPart インスタンスに追加できます。API Gateway は、汎用 API エンティティの DocumentationPart から該当する Swagger ドキュメント属性を抽出し、全般的な location パターンに一致するか、正確な値に一致する location フィールドを持つ特定の API エンティティに挿入します。ただし、特定のエンティティに DocumentationPart インスタンスがすでに関連付けられている場合を除きます。この動作は、より全般的な仕様の API エンティティからのコンテンツ継承とも呼ばれます。

コンテンツ継承は、APIAUTHORIZERMETHODMODELREQUEST_BODY、または RESOURCE タイプの API エンティティには適用されません。

API エンティティが複数の DocumentationPart の位置パターンに一致する場合、そのエンティティは優先度と具体性が最も高い位置フィールドを持つドキュメントパーツを継承します。優先順位は、path > statusCode です。path フィールドと一致させるため、API Gateway は最も具体的なパス値を持つエンティティを選択します。次の表に、いくつかの例とともにこれを示します。

ケース path statusCode name 解説
1 /pets * id

この位置パターンに関連付けられたドキュメントは、位置パターンに一致するエンティティによって継承されます。

2 /pets 200 id

この位置パターンに関連付けられたドキュメントは、ケース 1 とケース 2 の両方が一致する場合に位置パターンに一致するエンティティによって継承されます。ケース 2 の方がケース 1 より具体的だからです。

3 /pets/petId * id

この位置パターンに関連付けられたドキュメントは、ケース 1、2、および 3 が一致する場合に位置パターンに一致するエンティティによって継承されます。ケース 3 の方がケース 2 より優先度が高く、ケース 1 より具体的だからです。

ここでは、汎用的な DocumentationPart インスタンスと具体的なインスタンスの違いを別の例で示します。上書きされていない限り、全般的なエラーメッセージ "Invalid request error"400 エラーレスポンスの Swagger 定義に挿入されます。

{ "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" }

次のように上書きすると、/pets リソースでのすべてのメソッドに対する 400 レスポンスに、説明 "Invalid petId specified" が代わりに挿入されます。

{ "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" }

DocumentationPart の有効な位置フィールド

次の表に、特定のタイプの API エンティティに関連付けられた DocumentationPart リソースの有効なフィールド、必須のフィールド、および該当するデフォルト値を示します。

API エンティティ

有効な位置フィールド

必須の位置フィールド デフォルトフィールド値 継承可能なコンテンツ
API
{ "location": { "type": "API" }, ... }
type 該当なし いいえ
リソース
{ "location": { "type": "RESOURCE", "path": "resource_path" }, ... }
type path の初期値は です。/ いいえ
メソッド
{ "location": { "type": "METHOD", "path": "resource_path", "method": "http_verb" }, ... }
type pathmethod のデフォルト値は、それぞれ /* です。 はい。プレフィックスにより path に一致し、任意の値の method に一致します。
クエリパラメーター
{ "location": { "type": "QUERY_PARAMETER", "path": "resource_path", "method": "HTTP_verb", "name": "query_parameter_name" }, ... }
type pathmethod のデフォルト値は、それぞれ /* です。 はい。プレフィックスにより path に一致し、正確な値により method に一致します。
リクエスト本文
{ "location": { "type": "REQUEST_BODY", "path": "resource_path", "method": "http_verb" }, ... }
type pathmethod のデフォルト値は、それぞれ /* です。 はい。プレフィックスにより path に一致し、正確な値により method に一致します。
リクエストヘッダーパラメーター
{ "location": { "type": "REQUEST_HEADER", "path": "resource_path", "method": "HTTP_verb", "name": "header_name" }, ... }
typename pathmethod のデフォルト値は、それぞれ /* です。 はい。プレフィックスにより path に一致し、正確な値により method に一致します。
リクエストパスパラメーター
{ "location": { "type": "PATH_PARAMETER", "path": "resource/{path_parameter_name}", "method": "HTTP_verb", "name": "path_parameter_name" }, ... }
typename pathmethod のデフォルト値は、それぞれ /* です。 はい。プレフィックスにより path に一致し、正確な値により method に一致します。
レスポンス
{ "location": { "type": "RESPONSE", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type pathmethodstatusCode のデフォルト値は、それぞれ /** です。 はい。プレフィックスにより path に一致し、正確な値により methodstatusCode に一致します。
レスポンスヘッダー
{ "location": { "type": "RESPONSE_HEADER", "path": "resource_path", "method": "http_verb", "statusCode": "status_code", "name": "header_name" }, ... }
typename pathmethodstatusCode のデフォルト値は、それぞれ /** です。 はい。プレフィックスにより path に一致し、正確な値により methodstatusCode に一致します。
レスポンス本文
{ "location": { "type": "RESPONSE_BODY", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type pathmethodstatusCode のデフォルト値は、それぞれ /** です。 はい。プレフィックスにより path に一致し、正確な値により methodstatusCode に一致します。
オーソライザー
{ "location": { "type": "AUTHORIZER", "name": "authorizer_name" }, ... }
type 該当なし いいえ
モデル
{ "location": { "type": "MODEL", "name": "model_name" }, ... }
type 該当なし いいえ

ドキュメントバージョン

ドキュメントバージョンは、API の DocumentationParts コレクションのスナップショットであり、バージョン識別子でタグ付けされます。API のドキュメントを発行するには、ドキュメントバージョンを作成して API ステージに関連付け、そのステージ固有のバージョンの API ドキュメントを外部 Swagger ファイルにエクスポートします。API Gateway では、ドキュメントスナップショットが DocumentationVersion リソースとして表現されます。

API を更新するとき、新しいバージョンの API を作成します。API Gateway では、DocumentationVersions コレクションを使用してすべてのドキュメントバージョンを維持します。