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

Question

我有 JSON 架构文件，其中属性之一定义为

string

或

null

:

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

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

type:
  - 'null'
  - string

但是 Swagger 编辑器显示错误：

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

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

Answer 1

这取决于 OpenAPI 版本。

开放API 3.1

您的示例在 OpenAPI 3.1（2021-02-15 发布）中有效，它与 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 Schema 风格（“扩展子集”）。区别之一是

type

必须是单一类型，不能是类型列表。也没有

'null'

类型；相反，

nullable

关键字充当

type

修饰符以允许

null

值。

开放API 2.0

版本 2 不支持

'null'

作为数据类型，所以你运气不好。您只能使用

type: string

。但有些工具支持供应商扩展

x-nullable: true

来指示可为空的属性。

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