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

EN

这取决于OpenAPI版本。

OpenAPI 3.1

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

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

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

上面的代码相当于：

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

OAS3.0.x(见下文)中使用的nullable关键字在OAS3.1中不存在，已将其删除以支持'null'类型。

OpenAPI 3.0.x

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

type: string
nullable: true

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

OpenAPI 2.0

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

考虑迁移到OpenAPI v3以获得对nulls的适当支持。