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

小开

最佳答案

这取决于 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 语法不同，因为3.0. x 以下的 OpenAPI 版本使用自己的 JSON 模式的风格(“扩展子集”)。其中一个区别是，type必须是单一类型，不能是类型列表。此外，没有 'null'类型; 相反，nullable关键字充当 type修饰符，以允许 null值。

OpenAPI 2.0

OAS2不支持 'null'作为数据类型，因此您的运气不佳。您只能使用 type: string。然而，有些工具支持 x-nullable: true作为供应商扩展，尽管 null 不是 OpenAPI 2.0规范的一部分。

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