amazon-web-services - AWS API 网关 : Documentation Swagger export model type null ignored

Question

这个问题在这里已经有了答案:





How to define a property that can be string or null in OpenAPI (Swagger)?

(1 个回答)


2年前关闭。




我在将 AWS 的 API 网关文档导出到 Swagger 时遇到问题。
我有一个包含空类型的 JSON 模式模型的文档部分，例如:

{
  "title": "Incident",
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
        "type": "string"
    },
    "createdAt": {
        "type": "string"
    },
    "updatedAt": {
        "type": ["string", "null"]
    }
  }
}

它适用于验证，它允许我为 updatedAt 字段发送空值。但是，在这种情况下，当我将文档导出到 Swagger 时，我只有这是我的 swagger 文件:

{
  "title": "Incident",
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
        "type": "string"
    },
    "createdAt": {
        "type": "string"
    }
  }
}

我的 updatedAt 字段被简单地忽略了，如果我设置了，我也会遇到同样的问题

"type": "null"

这确实有问题，因为我需要能够发送空值，在这种情况下，我的 swagger 文档缺少模型中的某些字段。

有什么方法可以在 JSON Schema 中定义一个不会被 AWS API Gateway 忽略但仍然允许我发送空值的类型？

谢谢您的帮助。

[编辑]

原来“可空”:真正的解决方案不适合这种情况。
API Gateway 似乎使用 OAI V2 并且不支持可空。
然而，当我们将模型导出到 Swagger(在本例中使用 OAI V3)时，我们会丢失 null 类型。总之，我需要找到一个适用于 OAI V2 和 V3 的空类型解决方案。

Answer 1

虽然 JSON Schema 支持 null 类型，但 OpenAPI 规范(以前的 Swagger)不支持。

Primitive data types in the OAS are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer as a type is also supported and is defined as a JSON number without a fraction or exponent part. null is not supported as a type (see nullable for an alternative solution). Models are defined using the Schema Object, which is an extended subset of JSON Schema Specification Wright Draft 00.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types

相反，如果您希望可以为空，您可以使用 "nullable": true 的附加属性。 ，根据 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-20

OpenAPI 定义的“Schema Object”是 JSON Schema 的子超集。