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

Posted 2023-02-26

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

【英文标题】：How to re-use my x-amazon-apigateway-integration definition throughout Swagger YAML document?

【发布时间】：2019-04-17 05:37:55

【问题描述】：

我目前正在使用 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 网关时，我收到以下错误：

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

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

提前感谢您的帮助。

【参考方案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。

【讨论】：

谢谢。这非常有效，感谢您在可能无法解析的 API Gateway 上添加最后一段。我确实必须通过codebeautify.org/yaml-to-json-xml-csv 运行它才能工作

嘿嘿，谢谢。链接到我发现相同的github线程。关键是Metadata 关键：github.com/aws/serverless-application-model/issues/…

【参考方案2】：

截至 2020 年 4 月 24 日，AWS API Gateway 似乎不支持在 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.

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

【讨论】：

您是否知道这方面的一个未解决问题？无法引用集成有点糟糕，并且会线性增加配置量。

不幸的是，这只支持 HTTP API。更多信息：github.com/awsdocs/amazon-api-gateway-developer-guide/issues/65