如何在 OpenAPI (Swagger) 中定义一个可以是字符串或 null 的属性？

我有 JSON 模式文件，其中一个属性定义为string or null:

"type":["string", "null"]

当转换为 YAML（与 OpenAPI/Swagger 一起使用）时，它将变为：

type:
  - 'null'
  - string

但 Swagger 编辑器显示错误：

模式“type”键必须是字符串

在 OpenAPI 中定义可为 null 的属性的正确方法是什么？

这取决于 OpenAPI 版本。

开放API 3.1

您的示例在 OpenAPI 3.1 中有效，它与 JSON Schema 2020-12 完全兼容。

type:
  - 'null'   # Note the quotes around 'null'
  - string

# same as
type: ['null', string]

上式等价于：

oneOf:
  - type: 'null'   # Note the quotes around 'null'
  - type: string

The nullableOAS 3.0.x 中使用的关键字（见下文）在 OAS 3.1 中不存在，它被删除以支持'null' type.

开放API 3.0.x

可空字符串定义如下：

type: string
nullable: true

这与 JSON Schema 语法不同，因为 3.0.x 以下的 OpenAPI 版本使用自己的JSON 模式的风格（“扩展子集”）。差异之一是type必须是单一类型，不能是类型列表。还有没有'null'类型;相反，nullable关键字作为type修饰符允许null values.

开放API 2.0

OAS2 不支持'null'作为数据类型，所以你运气不好。你只能使用type: string。不过，有些工具支持x-nullable: true作为供应商扩展，即使 null 不是 OpenAPI 2.0 规范的一部分。

考虑迁移到 OpenAPI v.3 以获得对 null 的适当支持。