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

Question

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

要么我不理解应该如何定义定义，要么我没有把它放在正确的位置，要么两者兼而有之。我已经尝试在 'definitions' 中定义这个定义，并作为它自己的密钥下的一些别名。定义（删除了关键信息）是：

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 网关导入时收到的错误是 'Unable to parse API definition because of a malformed integration at path /'

我也试过在 'definitions' 下定义它，并使用 'ref' 访问它：

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 网关时，我收到以下错误：

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

无法为 'Amazon' 创建模型：指定的模型无效：验证结果：警告：[]，错误：[指定的模型架构无效。不支持的关键字：["x-amazon-apigateway-integration"]]
此外，还发现了这些警告：
'POST /' 的未知集成类型 'null'。忽略。

预先感谢您的帮助。

Answer 1

使用 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。

Answer 2

截至 2020 年 4 月 24 日，似乎 AWS API 网关不支持在 OpenAPI v3 文件中引用 x-amazon-apigateway-integration 组件，因为试图从 https://docs.aws.amazon.com/apigateway/latest/developerguide/api-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.

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

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

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

yaml

amazon-web-services

swagger

openapi