Menu
Amazon API Gateway
Developer Guide

API Gateway Extensions to Swagger

The API Gateway extensions support the AWS-specific authorization and API Gateway-specific API integrations. In this section, we will describe the API Gateway extensions to the Swagger specification.

Tip

To understand how the API Gateway extensions are used in an app, you can use the API Gateway console to create an API and export it to a Swagger definition file. For more information on how to export an API, see Export an API.

x-amazon-apigateway-any-method Object

Specifies the Swagger Operation Object for the API Gateway catch-all ANY method in a Swagger Path Item Object. This object can exist alongside other Operation objects and will catch any HTTP method that was not explicitly declared.

The following table lists the properties extended by API Gateway. For the other Swagger Operation properties, see the Swagger specification.

Properties

Property Name Type Description
x-amazon-apigateway-integration x-amazon-apigateway-integration Specifies the integration of the method with the back end. This is an extended property of the Swagger Operation object. The integration can be of type AWS, AWS_PROXY, HTTP, HTTP_PROXY, or MOCK.

x-amazon-apigateway-any-method Example

The following example integrates the ANY method on a proxy resource, {proxy+}, with a Lambda function, 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 Object

Defines a custom authorizer to be applied for authorization of method invocations in API Gateway. This object is an extended property of the Swagger Security Definitions Operation object.

Properties

Property Name Type Description
type string

The type of the authorizer. This is a required property and the value must be "token".

authorizerUri string

The Uniform Resource Identifier (URI) of the authorizer (a Lambda function). For example,

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

Credentials required for the authorizer, if any, in the form of an ARN of an IAM execution role. For example, "arn:aws:iam::account-id:IAM_role".

identityValidationExpression string

A regular expression for validating the incoming identity. For example, "^x-[a-z]+".

authorizerResultTtlInSeconds string

The number of seconds during which the resulting IAM policy is cached.

x-amazon-apigateway-authorizer Example

The following Swagger security definitions example specifies a custom authorizer named 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 } } }

The following Swagger operation object snippet sets the GET /http to use the custom authorizer specified above.

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 Property

Specify the type of a custom authorizer. It is parsed by the API Gateway API import and export features.

This property is an extended property of the Swagger Security Definitions Operation object.

x-amazon-apigateway-authtype Example

The following example sets the type of a custom authorizer using 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" : { ... } }

The following security definition example specifies authorization using AWS Signature Version 4:

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

x-amazon-apigateway-binary-media-types Property

Specifies the list of binary media types to be supported by API Gateway, such as application/octet-stream, image/jpeg, etc. This extension is a JSON Array.

x-amazon-apigateway-binary-media-types Example

The following example shows the encoding lookup order of an API.

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

x-amazon-apigateway-documentation Object

Defines the documentation parts to be imported into API Gateway. This object is a JSON object containing an array of the DocumentationPart instances.

Properties

Property Name Type Description
documentationParts Array

An array of the exported or imported DocumentationPart instances.

version String

The version identifier of the snapshot of the exported documentation parts.

x-amazon-apigateway-documentation Example

The following example of the API Gateway extension to Swagger defines DocumentationParts instances to be imported to or exported from an API in API Gateway.

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 Object

Specifies details of the back-end integration used for this method. This extension is an extended property of the Swagger Operation object. The result is an API Gateway integration object.

Properties

Property Name Type Description
cacheKeyParameters An array of string A list of request parameters whose values are to be cached.
cacheNamespace string An API-specific tag group of related cached parameters.
credentials string

For AWS IAM role-based credentials, specify the ARN of an appropriate IAM role. If unspecified, credentials will default to resource-based permissions that must be added manually to allow the API to access the resource. For more information, see Granting Permissions Using a Resource Policy. Note: when using IAM credentials, please ensure that AWS STS regional endpoints are enabled for the region where this API is deployed for best performance.

contentHandling string Request payload encoding conversion types. Valid values are 1) CONVERT_TO_TEXT, for converting a binary payload into a Base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT_TO_BINARY, for converting a text payload into Base64-decoded blob or passing through a binary payload natively without modification.
httpMethod string The HTTP method used in the integration request. For Lambda function invocations, the value must be POST.
passthroughBehavior string Specifies how a request payload of unmapped content type is passed through the integration request without modification. Supported values are when_no_templates, when_no_match, and never. For more information, see Integration.passthroughBehavior.
requestParameters x-amazon-apigateway-integration.requestParameters Specifies mappings from method request parameters to integration request parameters. Supported request parameters are querystring, path, header, and body.
requestTemplates x-amazon-apigateway-integration.requestTemplates Mapping templates for a request payload of specified MIME types.
responses x-amazon-apigateway-integration.responses Defines the method's responses and specifies desired parameter mappings or payload mappings from integration responses to method responses.
type string The type of integration with the specified back end. The valid value is http (for integration with an HTTP back end) or aws (for integration with AWS Lambda functions or other AWS services, such as DynamoDB, SNS or SQS).
uri string The endpoint URI of the back end. For integrations of the aws type, this is an ARN value. For the HTTP integration, this is the URL of the HTTP endpoint including the https or http scheme.

x-amazon-apigateway-integration Example

The following example integrates an API's POST method with a Lambda function in the back end. For demonstration purposes, the sample mapping templates shown in requestTemplates and responseTemplates of the examples below are assumed to apply to the following JSON-formatted payload: { "name":"value_1", "key":"value_2", "redirect": {"url" :"..."} } to generate a JSON output of { "stage":"value_1", "user-id":"value_2" } or an XML output of <stage>value_1</stage>.

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'" } } } }

Note that double quotes (") of the JSON string in the mapping templates must be string-escaped (\").

x-amazon-apigateway-integration.requestTemplates Object

Specifies mapping templates for a request payload of the specified MIME types.

Properties

Property Name Type Description
MIME type string

An example of the MIME type is application/json. For information about creating a mapping template, see Mapping Templates.

x-amazon-apigateway-integration.requestTemplates Example

The following example sets mapping templates for a request payload of the application/json and application/xml MIME types.

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 Object

Specifies mappings from named method request parameters to integration request parameters. The method request parameters must be defined before being referenced.

Properties

Property Name Type Description
integration.request.<param-type>.<param-name> string

The value must be a predefined method request parameter of the method.request.<param-type>.<param-name> format, where <param-type> can be querystring, path, header, or body. For the body parameter, the <param-name> is a JSON path expression without the $. prefix.

x-amazon-apigateway-integration.requestParameters Example

The following request parameter mappings example translates a method request's query (version), header (x-user-id) and path (service) parameters to the integration request's query (stage), header (x-userid), and path parameters (op), respectively.

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 Object

Defines the method's responses and specifies parameter mappings or payload mappings from integration responses to method responses.

Properties

Property Name Type Description
Response status pattern x-amazon-apigateway-integration.response

Selection regular expression used to match the integration response to the method response. For HTTP integrations, this regex applies to the integration response status code. For Lambda invocations, the regex applies to the errorMessage field of the error information object returned by AWS Lambda as a failure response body when the Lambda function execution throws an exception.

Note

The Response status pattern property name refers to a response status code or regular expression describing a group of response status codes. It does not correspond to any identifier of an IntegrationResponse resource in the API Gateway REST API.

x-amazon-apigateway-integration.responses Example

The following example shows a list of responses from 2xx and 302 responses. For the 2xx response, the method response is mapped from the integration response's payload of the application/json or application/xml MIME type. This response uses the supplied mapping templates. For the 302 response, the method response returns a Location header whose value is derived from the redirect.url property on the integration response's payload.

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 Object

Defines a response and specifies parameter mappings or payload mappings from the integration response to the method response.

Properties

Property Name Type Description
statusCode string

HTTP status code for the method response; for example, "200". This must correspond to a matching response in the Swagger Operation responses field.

responseTemplates x-amazon-apigateway-integration.responseTemplates

Specifies MIME type-specific mapping templates for the response’s payload.

responseParameters x-amazon-apigateway-integration.responseParameters

Specifies parameter mappings for the response. Only the header and body parameters of the integration response can be mapped to the header parameters of the method.

contentHandling string Response payload encoding conversion types. Valid values are 1) CONVERT_TO_TEXT, for converting a binary payload into a Base64-encoded string or converting a text payload into a utf-8-encoded string or passing through the text payload natively without modification, and 2) CONVERT_TO_BINARY, for converting a text payload into Base64-decoded blob or passing through a binary payload natively without modification.

x-amazon-apigateway-integration.response Example

The following example defines a 302 response for the method that derives a payload of the application/json or application/xml MIME type from the back end. The response uses the supplied mapping templates and returns the redirect URL from the integration response in the method's Location header.

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 Object

Specifies mapping templates for a response payload of the specified MIME types.

Properties

Property Name Type Description
MIME type string

Specifies a mapping template to transform the integration response body to the method response body for a given MIME type. For information about creating a mapping template, see Mapping Templates. An example of the MIME type is application/json.

x-amazon-apigateway-integration.responseTemplate Example

The following example sets mapping templates for a request payload of the application/json and application/xml MIME types.

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 Object

Specifies mappings from integration method response parameters to method response parameters. Only the header and body types of the integration response parameters can be mapped to the header type of the method response.

Properties

Property Name Type Description
method.response.header.<param-name> string

The named parameter value can be derived from the header and body types of the integration response parameters only.

x-amazon-apigateway-integration.responseParameters Example

The following example maps body and header parameters of the integration response to two header parameters of the method response.

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 Property

Specifies a request validator, by referencing a request_validator_name of the x-amazon-apigateway-request-validators map, to enable request validation on the containing API or a method. The value of this extension is a JSON string.

This extension can be specified at the API level or at the method level. The API-level validator applies to all of the methods unless it is overridden by the method-level validator.

x-amazon-apigateway-request-validator Example

The following example applies the basic request validator at the API level while applying the parameter-only request validator on the POST /validation request.

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 Object

Defines the supported request validators for the containing API as a map between a validator name and the associated request validation rules. This extension applies to an API.

Properties

Property Name Type Description

request_validator_name

x-amazon-apigateway-request-validators.requestValidator

Specifies the validation rules consisting of the named validator. For example:

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

To apply this validator to a specific method, reference the validator name (basic) as the value of the x-amazon-apigateway-request-validator property.

x-amazon-apigateway-request-validators Example

The following example shows a set of request validators for an API as a map between a validator name and the associated request validation rules.

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 Object

Specifies the validation rules of a request validator as part of the x-amazon-apigateway-request-validators map definition.

Properties

Property Name Type Description

validateRequestBody

Boolean

Specifies whether to validate the request body (true) or not (false).

validateRequestParameters

Boolean

Specifies whether to validate the required request parameters (true) or not (false).

x-amazon-apigateway-request-validators.requestValidator Example

The following example shows a parameter-only request validator:

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