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

Swagger に対する API Gateway 拡張

API Gateway 拡張では、AWS 固有の認証および API Gateway 固有の API 統合がサポートされています。このセクションでは、Swagger の仕様に対する API Gateway 拡張について説明します。

ヒント

アプリでの API Gateway 拡張機能の使用方法を理解するには、API Gateway コンソールを使用して API を作成し、Swagger 定義ファイルにエクスポートできます。API のエクスポート方法の詳細については、「API をエクスポートする」を参照してください。

x-amazon-apigateway-any-method オブジェクト

Swagger Path Item オブジェクトの API Gateway キャッチオール ANY メソッドの Swagger Operation オブジェクトを指定します。このオブジェクトは、他の Operation オブジェクトとともに指定でき、明示的に宣言されていない HTTP メソッドをキャッチします。

次の表は、API Gateway が拡張するプロパティを示します。他の Swagger Operation プロパティについては、Swagger の仕様を参照してください。

プロパティ

プロパティ名 タイプ 説明
x-amazon-apigateway-integration x-amazon-apigateway-integration メソッドとバックエンドの統合を指定します。これは、Swagger Operation オブジェクトの拡張プロパティです。統合のタイプは、AWSHTTPAWS_PROXYHTTP_PROXY、または MOCK です。

x-amazon-apigateway-any-method の例

次の例では、プロキシリソース {proxy+}ANY メソッドで Lambda 関数 TestSimpleProxy と統合しています。

Copy
"/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:TestSimpleProxy/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "type": "aws_proxy" }

x-amazon-apigateway-authorizer オブジェクト

API Gateway でのメソッド呼び出しの許可に適用されるカスタム認証を定義します。このオブジェクトは、Swagger Security Definitions Operation オブジェクトの拡張プロパティです。

プロパティ

プロパティ名 タイプ 説明
type string

認証のタイプ。これは必須のプロパティで、値は "token" である必要があります。

authorizerUri string

承認 (Lambda 関数) の Uniform Resource Identifier (URI)。たとえば、

Copy
"arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:auth_function_name/invocations"
authorizerCredentials string

IAM 実行ロールの ARN 形式の、認証で必要な認証情報 (ある場合)。たとえば、"arn:aws:iam::account-id:IAM_role"。

identityValidationExpression string

入力のアイデンティティを検証するための正規表現。たとえば、"^x-[a-z]+" などです。

authorizerResultTtlInSeconds string

作成される IAM ポリシーがキャッシュされる秒数。

x-amazon-apigateway-authorizer の例

次の Swagger セキュリティ定義の例では、test-authorizer というカスタム承認を指定します。

Copy
"securityDefinitions" : { "test-authorizer" : { "type" : "apiKey", // Required and the value must be "apiKey" for an API Gateway API. "name" : "Authorization", // The source header name identifying this authorizer. "in" : "header", // Required and the value must be "header" for an AAPI Gateway API. "x-amazon-apigateway-authtype" : "oauth2", // Specifies the authorization mechanism for the client. "x-amazon-apigateway-authorizer" : { // An API Gateway custom authorizer definition "type" : "token", // Required property and the value must "token" "authorizerUri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations", "authorizerCredentials" : "arn:aws:iam::account-id:role", "identityValidationExpression" : "^x-[a-z]+", "authorizerResultTtlInSeconds" : 60 } } }

次の Swagger オペレーションオブジェクトのスニペットでは、上記で指定されたカスタム認証を使用するよう GET /http を設定します。

Copy
"/http" : { "get" : { "responses" : { }, "security" : [ { "test-authorizer" : [ ] } ], "x-amazon-apigateway-integration" : { "type" : "http", "responses" : { "default" : { "statusCode" : "200" } }, "httpMethod" : "GET", "uri" : "http://api.example.com" } } }

x amazon-apigateway-authtype プロパティ

カスタム承認のタイプを指定します。これは API Gateway API のインポートおよびエクスポート機能で解析されます。

このプロパティは、Swagger Security Definitions Operation オブジェクトの拡張プロパティです。

x-amazon-apigateway-authtype の例

次の例では、OAuth 2 を使用してカスタム認証のタイプを設定します。

Copy
"cust-authorizer" : { "type" : "...", // required "name" : "...", // name of the identity source header "in" : "header", // must be header "x-amazon-apigateway-authtype" : "oauth2", // Specifies the authorization mechanism for the client. "x-amazon-apigateway-authorizer" : { ... } }

以下のセキュリティ定義の例では、AWS 署名バージョン 4 を使用して認証を指定します。

Copy
"sigv4" : { "type" : "apiKey", "name" : "Authorization", "in" : "header", "x-amazon-apigateway-authtype" : "awsSigv4" }

x-amazon-apigateway-binary-media-types のプロパティ

API Gateway がサポートする必要があるバイナリメディアタイプのリストを指定します (application/octet-streamimage/jpeg など)この拡張は JSON 配列です。

x-amazon-apigateway-binary-media-types の例

次の例は、API のエンコード検索順序を示しています。

Copy
"x-amazon-apigateway-binary-media-types: [ "application/octet", "image/jpeg" ]

x-amazon-apigateway-documentation オブジェクト

API Gateway にインポートするドキュメントパーツを定義します。このオブジェクトは、DocumentationPart インスタンスの配列を含む JSON オブジェクトです。

プロパティ

プロパティ名 タイプ 説明
documentationParts Array

エクスポートまたはインポートする DocumentationPart インスタンスの配列。

バージョン String

エクスポートするドキュメントパーツのスナップショットのバージョン識別子。

x-amazon-apigateway-documentation の例

Swagger への API Gateway 拡張の次の例では、API Gateway で API にインポートまたはエクスポートする DocumentationParts インスタンスを定義します。

Copy
{ ... "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" } } }, { … // Another DocumentationPart instance } ] } }

x-amazon-apigateway-integration オブジェクト

このメソッドのために使用するバックエンド統合の詳細を指定します。この拡張は、Swagger Operation オブジェクトの拡張プロパティです。結果は、API Gateway integration オブジェクトです。

プロパティ

プロパティ名 タイプ 説明
cacheKeyParameters string の配列 値がキャッシュされるリクエストパラメーターのリスト。
cacheNamespace string キャッシュされた関連パラメーターの API 固有のタググループ。
認証情報 string

AWS IAM ロールベースの認証情報については、該当する IAM ロールの ARN を指定します。指定しない場合、認証情報はデフォルトでリソースベースのアクセス権限に設定されます。API がリソースにアクセスできるようにするためには、リソースベースのアクセス権限を手動で追加する必要があります。詳細については、「Granting Permissions Using a Resource Policy」を参照してください。注意: IAM 認証情報を使用するときは、この API が最適なパフォーマンスのためにデプロイされているリージョンで AWS STS リージョンのエンドポイントが有効化されていることを確認してください。

contentHandling string リクエストのペイロードエンコード変換タイプ。有効な値は、1) バイナリペイロードを Base64 でエンコードされた文字列に変換する場合、テキストペイロードを utf-8 でエンコードされた文字列に変換する場合、または変更なしでテキストペイロードをネイティブに渡す場合は CONVERT_TO_TEXT、2) テキストペイロードを Base64 でデコードされた BLOB に変換する場合、または変更なしでバイナリペイロードをネイティブに渡す場合は CONVERT_TO_BINARY です。
httpMethod string 統合リクエストで使用される HTTP メソッドです。Lambda 関数の呼び出しでは、値は POST である必要があります。
passthroughBehavior string マッピングされていないコンテンツタイプのリクエストペイロードを、変更なしで統合リクエストに渡す方法を指定します。サポートされる値は when_no_templateswhen_no_matchnever です。詳細については、「Integration.passthroughBehavior」を参照してください。
requestParameters x-amazon-apigateway-integration.requestParameters メソッドリクエストパラメーターから統合リクエストパラメーターまでマッピングを指定します。サポートされているリクエストパラメーターは、querystringpathheader、および body です。
requestTemplates x-amazon-apigateway-integration.requestTemplates 指定された MIME タイプのリクエストペイロード用のマッピングテンプレートです。
レスポンス x-amazon-apigateway-integration.responses メソッドのレスポンスを定義し、統合レスポンスからメソッドレスポンスまで必要なパラメーターマッピングまたはペイロードマッピングを指定します。
type string 特定のバックエンドを持つ統合のタイプ。有効な値は、(HTTP バックエンドとの統合のための) http または (AWS Lambda 関数や、DynamoDB、SNS、または SQS など他の AWS 製品との統合のための) aws です。
uri string バックエンドのエンドポイント URI。aws タイプの統合の場合、この URI は ARN 値です。HTTP 統合の場合、この URI は、https または http スキームを含む HTTP エンドポイントの URL です。

x-amazon-apigateway-integration の例

次の例では、API の POST メソッドと Lambda 関数がバックエンドで統合されています。デモンストレーションの目的で、以下の例の requestTemplates および responseTemplates のサンプルマッピングテンプレートは、{ "stage":"value_1", "user-id":"value_2" } の JSON 出力または <stage>value_1</stage> の XML 出力を生成するために、{ "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} } という JSON 形式のペイロードに適用されるものとします。

Copy
"x-amazon-apigateway-integration" : { "type" : "aws", "uri" : "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:012345678901:function:HelloWorld/invocations", "httpMethod" : "POST", "credentials" : "arn:aws:iam::012345678901:role/apigateway-invoke-lambda-exec-role", "requestTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " }, "requestParameters" : { "integration.request.path.stage" : "method.request.querystring.version", "integration.request.querystring.provider" : "method.request.querystring.vendor" }, "cacheNamespace" : "cache namespace", "cacheKeyParameters" : [], "responses" : { "2\\d{2}" : { "statusCode" : "200", "responseParameters" : { "method.response.header.requestId" : "integration.response.header.cid" }, "responseTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " } }, "302" : { "statusCode" : "302", "responseParameters" : { "method.response.header.Location" : "integration.response.body.redirect.url" } }, "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" } } } }

マッピングテンプレートの JSON 文字列の二重引用符「"」は、エスケープ文字を付けて「\"」とする必要があります。

x-amazon-apigateway-integration.requestTemplates オブジェクト

指定された MIME タイプのリクエストペイロード用のマッピングテンプレートを指定します。

プロパティ

プロパティ名 タイプ 説明
MIME タイプ string

MIME タイプの例の 1 つが application/json です。マッピングテンプレート作成の詳細については、「マッピングテンプレート」を参照してください。

x-amazon-apigateway-integration.requestTemplates の例

次の例では、application/json および application/xml の MIME タイプのリクエストペイロード用のマッピングテンプレートが設定されています。

Copy
"requestTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " }

x-amazon-apigateway-integration.requestParameters オブジェクト

名前付きメソッドリクエストパラメーターから統合リクエストパラメーターまでマッピングを指定します。メソッドリクエストパラメーターは、参照される前に定義済みである必要があります。

プロパティ

プロパティ名 タイプ 説明
integration.request.<param-type>.<param-name> string

値は、事前に定義された method.request.<param-type>.<param-name> 形式のメソッドリクエストパラメーターである必要があります (ここで、<param-type>querystringpathheader、または body です)。body パラメーターの場合、<param-name>$. プレフィックスなしの JSON パス式です。

x-amazon-apigateway-integration.requestParameters

次のリクエストパラメーターのマッピングの例では、メソッドリクエストのクエリ (version)、ヘッダー (x-user-id)、およびパス (service) の各パラメーターが、統合リクエストのクエリ (stage)、ヘッダー (x-userid)、およびパス (op) の各パラメーターにそれぞれ変換されています。

Copy
"requestParameters" : { "integration.request.querystring.stage" : "method.request.querystring.version", "integration.request.header.x-userid" : "method.request.header.x-user-id", "integration.request.path.op" : "method.request.path.service" },

x-amazon-apigateway-integration.responses オブジェクト

メソッドのレスポンスを定義し、統合レスポンスからメソッドレスポンスまでパラメーターマッピングまたはペイロードマッピングを指定します。

プロパティ

プロパティ名 タイプ 説明
レスポンスステータスのパターン x-amazon-apigateway-integration.response

統合レスポンスをメソッドレスポンスに一致させるために使用する正規表現を選択します。HTTP 統合の場合、この正規表現が統合レスポンスのステータスコードに適用されます。Lambda の呼び出しでは、Lambda 関数の実行によって例外がスローされるときに、失敗レスポンスの本文として AWS Lambda から返されるエラー情報オブジェクトの errorMessage フィールドに正規表現が適用されます。

注記

レスポンスステータスパターンのプロパティ名は、レスポンスステータスコードまたはレスポンスステータスコードのグループを表す正規表現を示しています。これは、API Gateway REST API の IntegrationResponse リソースのどの識別子にも対応していません。

x-amazon-apigateway-integration.responses

次の例では、2xx から 302 までのレスポンスのリストが示されています。2xx レスポンスの場合、メソッドレスポンスは application/json または application/xml MIME タイプの統合レスポンスのペイロードからマッピングされます。このレスポンスでは、指定のマッピングテンプレートが使用されます。302 レスポンスの場合、メソッドレスポンスは Location ヘッダーを返します。ヘッダーの値は、統合レスポンスのペイロードで redirect.url プロパティから派生した値です。

Copy
"responses" : { "2\\d{2}" : { "statusCode" : "200", "responseTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " } }, "302" : { "statusCode" : "302", "responseParameters" : { "method.response.header.Location": "integration.response.body.redirect.url" } } }

x-amazon-apigateway-integration.response オブジェクト

レスポンスを定義し、統合レスポンスからメソッドレスポンスまでパラメーターマッピングまたはペイロードマッピングを指定します。

プロパティ

プロパティ名 タイプ 説明
statusCode string

メソッドレスポンスの HTTP ステータスコード (例: "200")。これは、Swagger Operation responses フィールドで一致しているレスポンスに対応している必要があります。

responseTemplates x-amazon-apigateway-integration.responseTemplates

レスポンスのペイロード用に MIME タイプ固有のマッピングテンプレートを指定します。

responseParameters x-amazon-apigateway-integration.responseParameters

レスポンス用にパラメーターマッピングを指定します。メソッドの header パラメーターにマッピングできるのは、統合レスポンスの header パラメーターおよび body パラメーターだけです。

contentHandling string レスポンスのペイロードエンコード変換タイプ。有効な値は、1) バイナリペイロードを Base64 でエンコードされた文字列に変換する場合、テキストペイロードを utf-8 でエンコードされた文字列に変換する場合、または変更なしでテキストペイロードをネイティブに渡す場合は CONVERT_TO_TEXT、2) テキストペイロードを Base64 でデコードされた BLOB に変換する場合、または変更なしでバイナリペイロードをネイティブに渡す場合は CONVERT_TO_BINARY です。

x-amazon-apigateway-integration.response

次の例では、バックエンドから application/json または application/xml の MIME タイプのペイロードを派生させるメソッド用の 302 レスポンスが定義されています。このレスポンスでは、指定のマッピングテンプレートが使用され、メソッドの Location ヘッダーで統合レスポンスからのリダイレクト URL が返されます。

Copy
{ "statusCode" : "302", "responseTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " }, "responseParameters" : { "method.response.header.Location": "integration.response.body.redirect.url" } }

x-amazon-apigateway-integration.responseTemplates オブジェクト

指定された MIME タイプのレスポンスペイロード用のマッピングテンプレートを指定します。

プロパティ

プロパティ名 タイプ 説明
MIME タイプ string

指定の MIME タイプで統合レスポンス本文をメソッドレスポンス本文に変換するマッピングテンプレートを指定します。マッピングテンプレート作成の詳細については、「マッピングテンプレート」を参照してください。MIME タイプの例の 1 つが application/json です。

x-amazon-apigateway-integration.responseTemplate の例

次の例では、application/json および application/xml の MIME タイプのリクエストペイロード用のマッピングテンプレートが設定されています。

Copy
"responseTemplates" : { "application/json" : "#set ($root=$input.path('$')) { \"stage\": \"$root.name\", \"user-id\": \"$root.key\" }", "application/xml" : "#set ($root=$input.path('$')) <stage>$root.name</stage> " }

x-amazon-apigateway-integration.responseParameters オブジェクト

統合メソッドレスポンスパラメーターからメソッドレスポンスパラメーターまでマッピングを指定します。メソッドレスポンスの header タイプにマッピングできるのは、統合レスポンスパラメーターの header タイプおよび body タイプだけです。

プロパティ

プロパティ名 タイプ 説明
method.response.header.<param-name> string

名前付きパラメーター値が派生するのは、統合レスポンスパラメーターの header タイプおよび body タイプからだけです。

x-amazon-apigateway-integration.responseParameters

次の例では、統合レスポンスの body および header の各パラメーターがメソッドレスポンスの 2 つの header パラメーターにマッピングされています。

Copy
"responseParameters" : { "method.response.header.Location" : "integration.response.body.redirect.url", "method.response.header.x-user-id" : "integration.response.header.x-userid" }

x-amazon-apigateway-request-validator プロパティ

x-amazon-apigateway-request-validators マップの request_validator_name を参照することでリクエストの検証を指定し、リクエストの検証が含まれる API またはメソッドでのリクエストの検証を有効にします。この拡張の値は、JSON 文字列です。

この拡張は、API レベルまたはメソッドレベルで指定できます。API レベルの検証は、メソッドレベルの検証によりオーバーライドされなければすべてのメソッドに適用されます。

x-amazon-apigateway-request-validator

次の例では、parameter-only リクエストの検証を POST /validation リクエストに適用すると同時に、basic リクエストの検証を API レベルで適用します。

Copy
{ "swagger": "2.0", "x-amazon-apigateway-request-validators" : { "basic" : { "validateRequestBody" : true, "validateRequestParameters" : true }, "params-only" : { "validateRequestBody" : false, "validateRequestParameters" : true } }, "x-amazon-apigateway-request-validator" : "basic", "paths": { "/validation": { "post": { "x-amazon-apigateway-request-validator" : "params-only", ... } }

x-amazon-apigateway-request-validators オブジェクト

リクエストの検証が含まれる API のサポートされるリクエストの検証を、検証名と関連するリクエスト検証ルールの間のマップとして定義します。この拡張は、API に適用されます。

プロパティ

プロパティ名 タイプ 説明

request_validator_name

x-amazon-apigateway-request-validators.requestValidator

指定された検証で構成される検証ルールを指定します。(例:

Copy
"basic" : { "validateRequestBody" : true, "validateRequestParameters" : true },

特定のメソッドにこの検証を適用するには、x-amazon-apigateway-request-validator プロパティの値として検証名 (basic) を参照してください。

x-amazon-apigateway-request-validators

次の例は、検証名と関連するリクエスト検証ルールの間のマップとして定義された、API のリクエストの検証のセットを示しています。

Copy
{ "swagger": "2.0", ... "x-amazon-apigateway-request-validators" : { "basic" : { "validateRequestBody" : true, "validateRequestParameters" : true }, "params-only" : { "validateRequestBody" : false, "validateRequestParameters" : true } }, ... }

x-amazon-apigateway-request-validators.requestValidator オブジェクト

リクエストの検証の検証ルールを x-amazon-apigateway-request-validators マップ定義の一部として指定します。

プロパティ

プロパティ名 タイプ 説明

validateRequestBody

Boolean

リクエスト本文を検証するか (true) しないか (false) を指定します。

validateRequestParameters

Boolean

必須のリクエストパラメーターを検証するか (true) しないか (false) を指定します。

x-amazon-apigateway-request-validators.requestValidator

次の例は、パラメーターのみのリクエストの検証を示しています。

Copy
"params-only": { "validateRequestBody" : false, "validateRequestParameters" : true }