aws-api-gateway - 如何在与 AWS API Gateway 兼容的 OpenAPI 3.0.x 中声明可空属性

Question

我们一直在使用 OpenAPI 3.0.x 规范，它增加了声明 nullable 属性的功能。

当我将此 OpenAPI 导入 AWS API Gateway 时，相应的模型不支持此可为 null 的设置。

有什么方法可以在 OpenAPI 3.0.x 中声明 nullable 属性，以便 AWS API 网关也使用此设置识别和配置底层模型？

示例 OpenAPI 规范

openapi: "3.0.2"
info:
  title: Test
  description: |
    API
  version: "0.1.0"
  license:
    name: Private
    url: https://fillme.one/license
servers:
  - url: /api/v1
paths:
  /accounts:
    post:
      operationId: repa
      responses:
        200:
          description: test
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                  nullable: true
              required:
                - date

生成模型的结果 JSON 模式文档

{
  "required" : [ "date" ],
  "type" : "object",
  "properties" : {
    "date" : {
      "type" : "string",
      "format" : "date-time"
    }
  }
}

显然，类型应该是 ["string", null] 的并集，但 AWS API Gateway 忽略了 OpenAPI 规范。

有什么帮助吗？

Answer 1

AWS API Gateway 需要 JSON 架构格式而非 OpenAPI 架构格式的模型。这是相关说明 from the documentation (强调我的):

API Gateway supports most of the OpenAPI 2.0 specification and the OpenAPI 3.0 specification, with the following exceptions:

• ...
• API Gateway models are defined using JSON schema draft 4, instead of the JSON schema used by OpenAPI.

这意味着 AWS API Gateway 需要 type: [string, 'null'] 而不是 type: string + nullable: true。

但是，类型:[string, 'null'] is not valid syntax在 OpenAPI 3.0 中(尽管在 OAS 3.1 中有效)。您可以做的是在将现有 OpenAPI 文件导入 AWS API Gateway 之前对其进行预处理，并将可空类型定义更改为 AWS 期望的格式/语法。您可以尝试使用 openapi-schema-to-json-schema 等工具.