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

Question

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.

Answer 1

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.