如何在OpenAPI（Swagger）中定义一个可为字符串或null的属性？

Question

我有一个JSON模式文件，其中一个属性被定义为string或null：

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

转换为YAML格式（用于OpenAPI / Swagger），它变成：

type:
  - 'null'
  - string

但Swagger编辑器显示错误:

模式中的“类型”关键字必须是字符串

在OpenAPI中定义可空属性的正确方式是什么？

- Vaibhav Patil

---

相关：如何在Swagger中指定属性可以为null或引用？。 - Helen

Answer 1

这取决于OpenAPI的版本。

OpenAPI 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

在OAS 3.0.x中使用的nullable关键字（见下文）在OAS 3.1中已经被移除，取而代之的是'null'类型。

OpenAPI 3.0.x

可为空的字符串定义如下：

type: string
nullable: true

这与JSON Schema语法不同，因为OpenAPI版本3.0.x及以下版本使用自己的JSON Schema扩展子集。其中一个区别是type必须是单个类型，不能是类型列表。此外，没有'null'类型;相反，nullable关键字作为type修饰符允许null值。

OpenAPI 2.0

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

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

- Helen

---

很好引用3.1规范中所述的内容。在https://swagger.io/specification/上阅读时，明确指出“不支持通过数组使用多个类型”。 - m.spyratos