How to re-use my x-amazon-apigateway-integration definition throughout Swagger YAML document?

user_4971293 0
Viewed 3581

I am currently using Swagger to define an API with many end-points, and each one of those end-points all have the same definition for the 'x-amazon-apigateway-integration' key. I would like to define this somewhere in the document, and re-use that definition through-out.

Either I am not understanding how the definition should be defined, I am not placing it in the correct location or a mix of the two. I have tried defining this definition within 'definitions', and as some alias under it's own key. The definition (with key information removed) is:

x-amazon-apigateway-integration:
  responses:
    default:
      statusCode: '200'
  passthroughBehavior: when_no_match
  httpMethod: POST
  uri: >-
    arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<lambda arn>/invocations
  credentials: '<role arn>'
  type: aws     
  requestTemplates: "application/json": "<object definition>"

I have tried defining this as an alias under it's own key (not definitions, but the same base scope):

amazon:
  Amazon: &Amazon
    - responses:
        default:
          statusCode: '200'
    - passthroughBehavior: when_no_match
    - httpMethod: POST
    - uri: >-
    arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<lambda arn>/invocations
    - credentials: '<role arn>'
    - type: aws     
    - requestTemplates:
      "application/json": "<object definition>"

To use, I have the following:

x-amazon-apigateway-integration:
  *Amazon

The error received on API Gateway import is 'Unable to parse API definition because of a malformed integration at path /'

I have also tried defining this under 'definitions', and using 'ref' to access it:

definitions:
  Amazon:
    type: object
    x-amazon-apigateway-integration:
      responses:
        default:
          statusCode: '200'
      passthroughBehavior: when_no_match
      httpMethod: POST
      uri: >-
          arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<lambda arn>/invocations
      credentials: '<role arn>'
      type: aws     
      requestTemplates:
        "application/json": "<object definition>"

To use, I have the following:

x-amazon-apigateway-integration:
  $ref: '#/definitions/Amazon'

On import to API Gateway I receive the following error(s):

Your API was not imported due to errors in the Swagger file.

  • Unable to create model for 'Amazon': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["x-amazon-apigateway-integration"]]
  • Additionally, these warnings were found:
  • Unknown integration type 'null' for 'POST /'. Ignoring.

Thank you in advance for your help.

swagger openapi amazon-web-services yaml
2 Answers

Using YAML anchors seems like a good idea. The correct syntax is as follows.

Add the following on the root level of your OpenAPI file:

x-definitions:      # <--- "x-" before "definitions" prevents it from being
                    #      attempted to be parsed as an OpenAPI Schema object.
  Amazon:
    type: object
    x-amazon-apigateway-integration: &Amazon   # <--- "&Amazon" is the anchor
      responses:
        default:
          statusCode: '200'
      passthroughBehavior: when_no_match
      httpMethod: POST
      uri: >-
          arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<lambda arn>/invocations
      credentials: '<role arn>'
      type: aws     
      requestTemplates:
        "application/json": "<object definition>"

Then you can refer to the anchor like this:

x-amazon-apigateway-integration: *Amazon

However, it might be that AWS parser does not support YAML anchors (&..., *...). In that case you can try pre-processing your definition using a parser that can resolve YAML anchors and then feed the resolved file to AWS.

user_1131160

As of 24th April 2020, it appears as though AWS API Gateway does not support referencing x-amazon-apigateway-integration components in OpenAPI v3 files, as trying to import the example from https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-extensions-integrations.html fails with

Your API was not imported due to errors in the Swagger file.
Unknown integration type 'null' for 'GET /'. Ignoring.
Unknown integration type 'null' for 'GET /pets'. Ignoring.
Unknown integration type 'null' for 'GET /checkout'. Ignoring.

It looks as though pre-processing the file is currently the only option to avoid repeated integration definitions

user_3231770
Related