使用 OpenAPI (swagger) JSON 模式定义对空值进行模式验证

Question

我正在寻找一种解决方案来解决 Swagger (OpenAPI) data types 和 JSON Schema 之间的数据类型处理空值的不兼容问题。

我们的 swagger 文件包含我们所有的架构定义，我想在我们的 API 测试中使用 JSON.Net Schema 进行架构验证步骤。

有效的 swagger 属性定义：

  "description": {
    "type": "string",
    "nullable": true
  }

空值的 JSON 架构验证将失败 (Invalid type. Expected String but got Null)。

如果我将可空属性定义替换为：

  "description": {
    "type": ["string", "null"]
  } 

null 值的验证会成功，但这会破坏swagger 语法。

Structural error at components.schemas.CalendarFunctionsDto.properties.description_EN.type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string

我找不到用于 .NET 的 OpenAPI 模式到 JSON 模式转换器。我试图弄清楚是否有一个简单的解决方案可以使用 JSON.Net Schema 来解决这个问题。我们的一些类型比上面的例子更复杂。我正在寻找一种适用于所有“可空”类型的解决方案。

理想情况下，我希望为输入保留有效的 swagger (OpenAPI 3.0) JSON 语法，以编程方式在 C# 中为所有可空属性执行一些拼写（转换架构，或调整验证，或任何其他创造性的解决方案），然后使用 JSON.Net Schema 验证架构。

Answer 1

Openapi 3.0.0/3.0.1/3.0.2/3.0.3 不支持 null 类型，它只支持 nullable。 JSON Schema 不支持 nullable，它支持 null 类型。 你能把你的规范更新到 Openapi v3.1.0 吗？ 该版本支持 null 类型。然后您可以使用以下选项之一：

选项 1（不太可能在 openapi 工具中工作，因为类型数组是新增功能）

  "description": {
    "type": ["string", "null"]
  } 

选项 2（更可能使用 openpi 工具，因为类型不是数组）

  "description": {
    "oneOf" [
        {"type": "string"},
        {"type": "null"},
    ]
  }