如何在OpenAPI（Swagger）中正确定义可为字符串或null的属性？

你遇到的这个错误是因为OpenAPI的类型定义规则和原生JSON Schema存在差异，直接用数组形式type: - 'null' - string并不符合OpenAPI的规范要求。下面分版本给你讲正确的实现方式：

OpenAPI 3.0+（推荐方案） #

OpenAPI 3.0及以上版本专门引入了nullable关键字来处理可空属性，这是官方推荐的标准写法，工具支持度也最好：

components:
  schemas:
    YourTargetSchema:
      type: object
      properties:
        yourNullableProperty:
          type: string
          nullable: true  # 标记该属性允许为null

这种写法清晰直观，Swagger编辑器完全认可，也严格符合OpenAPI的规范定义。

Swagger/OpenAPI 2.0（旧版本兼容方案） #

如果你还在使用OpenAPI 2.0（也就是Swagger 2.0），这个版本没有nullable关键字，需要用oneOf来模拟可空类型：

definitions:
  YourTargetSchema:
    type: object
    properties:
      yourNullableProperty:
        oneOf:
          - type: string
          - type: 'null'

不过要注意，这种写法在部分旧版Swagger工具里可能会有兼容性提示，长远来看还是建议升级到OpenAPI 3.x版本来获得更完善的支持。

另外补充一句：原生JSON Schema的type: ["string", "null"]写法虽然合法，但OpenAPI并没有完全照搬这个规则，尤其是在早期版本中，所以一定要用对应OpenAPI版本的专属写法来避免编辑器报错。

内容的提问来源于stack exchange，提问作者Vaibhav Patil