Amazon API Gateway Extension to OpenAPI

External

• https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html

Internal

• Amazon API Gateway

Organizatorium

• Example: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-as-lambda-proxy-export-swagger-with-extensions.html
• Proxy Integration Example with extension and HTTP https://docs.aws.amazon.com/apigateway/latest/developerguide/setup-http-integrations.html#api-gateway-set-up-http-proxy-integration-on-proxy-resource

Extensions

x-amazon-apigateway-integration

x-amazon-apigateway-integration

Integration

'x-amazon-apigateway-integration' specifies the details of the backend integration for a specific OpenAPI operation.

type

Integration type Reference

A string that specifies the integration type with the backend:

• "http", "http_proxy" defines integration with an HTTP backend.
• "aws_proxy" defines integration with a Lambda functions, via proxy integration.
• "aws" defines integration with other AWS services or with Lambda functions, via custom integration.
• "mock" defines mock integration

passthroughBehavior

Integration passthroughBehavior Reference

A string that specifies how a request body of an unmapped content will be passed through the integration request to the back end without transformation. A content type is unmapped if no mapping template is defined in the integration or the content type does not match any of the mapped content types, as specified in requestTemplates. Supported values:

• "when_no_templates": passes the method request body through the integration request to the back end without transformation when no mapping template is defined in the integration request. If a template is defined when this option is selected, the method request of an unmapped content-type will be rejected with an HTTP 415 Unsupported Media Type response.
• "when_no_match": passes the method request body through the integration request to the back end without transformation when the method request content type does not match any content type associated with the mapping templates defined in the integration request.
• "never": rejects the method request with an HTTP 415 Unsupported Media Type response when either the method request content type does not match any content type associated with the mapping templates defined in the integration request or no mapping template is defined in the integration request.

responses

x-amazon-apigateway-integration:
  ...
  responses:
    default:
      statusCode: "200"
      responseParameters:
        method.response.header.Access-Control-Allow-Origin: "'*'"
        method.response.header.Access-Control-Allow-Methods: "'DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT'"
        method.response.header.Access-Control-Allow-Headers: "'Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token'"

For responseParameters, the "'...'" syntax must be used, otherwise a syntax error is thrown.

requestTemplates

Integration requestTemplates Reference

x-amazon-apigateway-integration.requestTemplates Object

Represents a map of Velocity templates that are applied on the request payload based on the value of the Content-Type header sent by the client. The content type value is the key in this map, and the template (as a String) is the value.

x-amazon-apigateway-integration:
  ...
  requestTemplates:
    application/json: "{\"statusCode\": 200}"

Alos see:

Mapping Template

'x-amazon-apigateway-integration' Examples

HTTP Proxy Integration with a Non-Private Endpoint

Working HTTP proxy integration with a non-private endpoint. The endpoint is http://test.com:10001:

swagger: "2.0"
...
paths:
  /blue/v1/:
    get:
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema: {}
        401:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema:
            $ref: '#/definitions/RespMessage'
            originalRef: '#/definitions/RespMessage'
      x-amazon-apigateway-integration:
        type: http_proxy
        httpMethod: GET
        uri: http://test.com:10001/blue/v1/
        passthroughBehavior: when_no_match
        responses:
          default:
            statusCode: "200"
            responseParameters:
              method.response.header.Access-Control-Allow-Origin: '''*'''
definitions:
  ...

HTTP Proxy Integration with a Non-Private Endpoint, with Variable Path Elements

HTTP proxy integration with a non-private endpoint, with variable path elements. The endpoint is http://test.com:10001:

swagger: "2.0"
...
paths:
  /search/v1/{id}:
    get:
      parameters:
      - name: id
        in: path
        description: ""
        required: true
        type: string
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema: {}
        400:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema:
            $ref: '#/definitions/RespMessage'
            originalRef: '#/definitions/RespMessage'
      x-amazon-apigateway-integration:
        type: http_proxy
        httpMethod: GET
        uri: http://test.com:10001/search/v1/{id}
        passthroughBehavior: when_no_match
        requestParameters:
          integration.request.path.id: method.request.path.id
        responses:
          default:
            responseParameters:
              method.response.header.Access-Control-Allow-Origin: '''*'''
            statusCode: "200"
definitions:
  ...

HTTP Proxy Integration with a Private Endpoint

HTTP proxy integration with a private endpoint, with no variable path elements:

swagger: "2.0"
...
paths:
  /blue/v1/:
    get:
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema: {}
        401:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema:
            $ref: '#/definitions/RespMessage'
            originalRef: '#/definitions/RespMessage'
      x-amazon-apigateway-integration:
        type: http_proxy
        httpMethod: GET
        uri: http://test.com:10001/blue/v1/
        connectionType: "VPC_LINK"
        connectionId: "e4j4ut"
        passthroughBehavior: when_no_match
        responses:
          default:
            statusCode: "200"
            responseParameters:
              method.response.header.Access-Control-Allow-Origin: '''*'''
definitions:
  ...

Lambda Proxy Integration

swagger: "2.0"
...
paths:
  /search/v1/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        type: string
      responses:
        200:
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema: {}
      x-amazon-apigateway-integration:
        type: aws_proxy
        uri: arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:777777777777:function:lambda-example/invocations
        credentials: arn:aws:iam::777777777777:role/service-role/apigateway-lambda-invoker-role
        httpMethod: POST
        contentHandling: CONVERT_TO_TEXT
        passthroughBehavior: when_no_match
        responses:
          default:
            responseParameters:
              method.response.header.Access-Control-Allow-Origin: '''*'''
            statusCode: "200"

x-amazon-apigateway-gateway-responses

x-amazon-apigateway-integration.responses

x-amazon-apigateway-gateway-responses:
  DEFAULT_4XX:
    responseParameters:
      gatewayresponse.header.Access-Control-Allow-Methods: "'POST,OPTIONS'"
      gatewayresponse.header.Access-Control-Allow-Origin: "'*'"
      gatewayresponse.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'"
  DEFAULT_5XX:
    responseParameters:
      gatewayresponse.header.Access-Control-Allow-Methods: "'POST,OPTIONS'"
      gatewayresponse.header.Access-Control-Allow-Origin: "'*'"
      gatewayresponse.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'"