如何在 OpenAPI (Swagger) 中定义可以为字符串或空值的 属性？
How to define a property that can be string or null in OpenAPI (Swagger)?
我有 JSON 模式文件，其中一个属性被定义为 string 或 null:
"type":["string", "null"]
当转换为 YAML（与 OpenAPI/Swagger 一起使用）时，它变成：
type:
- 'null'
- string
但 Swagger 编辑器显示错误：
Schema "type" key must be a string
在 OpenAPI 中定义可空 属性 的正确方法是什么？
这取决于 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 中使用的 nullable 关键字。0.x（见下文）在 OAS 3.1 中不存在，它被删除以支持 'null' 类型。
OpenAPI 3.0.x
可空字符串定义如下：
type: string
nullable: true
这与 JSON 模式语法不同，因为 OpenAPI 版本高达 3。0.x 使用他们自己的 flavor of JSON Schema ("extended subset"). One of the differences is that the type must be a single type and cannot be a list of types. Also there's no 'null' type; instead, the nullable 关键字作为 type 修饰符来允许 null 值。
OpenAPI 2.0
OAS2 不支持 'null' 作为数据类型，所以你运气不好。您只能使用 type: string。但是，一些工具支持 x-nullable: true 作为供应商扩展，即使空值不是 OpenAPI 2.0 规范的一部分。
考虑迁移到 OpenAPI v.3 以获得对空值的适当支持。
我有 JSON 模式文件，其中一个属性被定义为 string 或 null:
"type":["string", "null"]
当转换为 YAML（与 OpenAPI/Swagger 一起使用）时，它变成：
type:
- 'null'
- string
但 Swagger 编辑器显示错误：
Schema "type" key must be a string
在 OpenAPI 中定义可空 属性 的正确方法是什么？
这取决于 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 中使用的 nullable 关键字。0.x（见下文）在 OAS 3.1 中不存在，它被删除以支持 'null' 类型。
OpenAPI 3.0.x
可空字符串定义如下：
type: string
nullable: true
这与 JSON 模式语法不同，因为 OpenAPI 版本高达 3。0.x 使用他们自己的 flavor of JSON Schema ("extended subset"). One of the differences is that the type must be a single type and cannot be a list of types. Also there's no 'null' type; instead, the nullable 关键字作为 type 修饰符来允许 null 值。
OpenAPI 2.0
OAS2 不支持 'null' 作为数据类型，所以你运气不好。您只能使用 type: string。但是，一些工具支持 x-nullable: true 作为供应商扩展，即使空值不是 OpenAPI 2.0 规范的一部分。
考虑迁移到 OpenAPI v.3 以获得对空值的适当支持。