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

Question

我有JSON架构文件，其中一个属性定义为string或null：

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

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

type:
  - 'null'
  - string

但Swagger编辑器显示错误：

  

Schema＆＃34; type＆＃34; key必须是一个字符串

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

Answer 1

type作为类型数组

type:
  - string
  - 'null'

在OpenAPI / Swagger中无效（即使它在JSON Schema中有效）。 OpenAPI的type关键字需要单一类型，不能是类型数组。

对null的支持取决于您使用的OpenAPI版本：

• 在 OpenAPI 3.0 中，使用nullable关键字定义可空类型：

  type: string
  nullable: true   # <----
  

• OpenAPI 2.0 不支持null作为数据类型，因此如果使用2.0，则运气不佳。您只能使用type: string。也就是说，有些工具支持x-nullable: true作为供应商扩展，即使空值不是OpenAPI 2.0规范的一部分。