OpenAPI 3.0.1下如何实现string或null类型的JSON校验与正常展示

核心问题梳理 #

你碰到的是OpenAPI 3.0.x版本与JSON Schema语法不兼容，同时校验工具和Swagger文档渲染的适配问题：

• OpenAPI 3.0.x不支持JSON Schema的"type": ["string", "null"]语法
• 标准的"type":"string"+"nullable":true写法可能因校验工具不支持OpenAPI扩展而失效
• 强行用数组类型会导致Swagger文档显示异常

可行解决方案 #

1. 用OpenAPI 3.0标准写法+适配校验工具

OpenAPI 3.0.x的官方规范就是用nullable:true来标记可空类型，如果你当前配置无法校验null，问题出在校验工具而非配置本身：

{
  "type": "string",
  "nullable": true
}

• 更换为支持OpenAPI 3.0扩展的校验工具，比如openapi-validator
• 升级Swagger UI/Editor到3.x及以上版本，确保它能正确识别nullable并渲染为string | null

2. 用oneOf语法做兼容兜底

如果无法升级工具，oneOf是OpenAPI 3.0支持的语法，既能实现string/null的校验，又能让Swagger文档正常显示：

{
  "oneOf": [
    { "type": "string" },
    { "type": "null" }
  ]
}

这个写法会被大多数校验工具正确解析，Swagger文档会显示为string or null，完全符合预期。

3. 避免踩坑：不要混用JSON Schema和OpenAPI语法

OpenAPI 3.0.x基于JSON Schema Draft 04，但做了不少修改和扩展，直接用Draft 07/2020-12的语法（比如数组类型）会导致工具兼容问题，必须遵循OpenAPI 3.0的规范写法。

内容的提问来源于stack exchange，提问作者Rockwell Rice