如何在整个 Swagger YAML 文档中重复使用我的 x-amazon-apigateway-integration 定义？

Question

我目前正在使用 Swagger 来定义具有许多端点的 API，并且这些端点中的每一个都对“x-amazon-apigateway-integration”键具有相同的定义。我想在文档的某处定义它，并在整个过程中重复使用该定义。

要么我不明白应该如何定义定义，我没有将它放在正确的位置或两者的混合。我尝试在“定义”中定义这个定义，并作为它自己的密钥下的一些别名。定义（删除了关键信息）是：

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

我尝试将其定义为它自己的密钥下的别名（不是定义，而是相同的基本范围）：

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

要使用，我有以下内容：

x-amazon-apigateway-integration:
  *Amazon

API Gateway 导入时收到的错误是“无法解析 API 定义，因为路径 / 中的集成格式错误”

我还尝试在“定义”下定义它，并使用“参考”来访问它：

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

要使用，我有以下内容：

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

在导入到 API Gateway 时，我收到以下错误：

由于 Swagger 文件中的错误，您的 API 未导入。

• 无法为“亚马逊”创建模型：指定的模型无效：验证结果：警告：[]，错误：[指定的模型架构无效。不支持的关键字：[“x-amazon-apigateway-integration”]]
• 此外，还发现了以下警告：
• “POST /”的未知集成类型“null”。无视。

预先感谢您的帮助。

Answer 1

截至 2020 年 4 月 24 日，AWS API Gateway 似乎不支持引用OpenAPI v3 文件中的组件，因为尝试从https://docs.aws.amazon.com/apigateway/latest/developerguide/api-x-amazon-apigateway-integration导入示例gateway-extensions-integrations.html失败并显示

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.

看来预处理文件是目前避免重复集成定义的唯一选择

Answer 2

使用 YAML 锚点似乎是个好主意。正确的语法如下。

在 OpenAPI 文件的根级别添加以下内容：

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

然后你可以像这样引用锚点：

x-amazon-apigateway-integration: *Amazon

但是，AWS 解析器可能不支持 YAML 锚点 ( &..., *...)。在这种情况下，您可以尝试使用可以解析 YAML 锚点的解析器来预处理您的定义，然后将解析后的文件提供给 AWS。