Swagger 2.0中properties与additionalProperties可取null值的规则问询

关于OpenAPI（Swagger）中null值的默认验证规则 #

这个问题其实戳中了OpenAPI（原Swagger）里一个容易混淆的细节：请求和响应的验证宽松度差异，以及schema默认规则对null值的限制，我来给你理清楚：

核心默认规则：nullable属性默认是false #

在OpenAPI 3.x的规范里，所有schema的nullable属性默认值都是false——意思是，只要你没明确写nullable: true，这个字段就不允许出现null值，只能符合指定的type类型。

那为什么你的请求里把height设为None（也就是null）没报错？这里大概率是两种情况：

• 你所谓的“设为None”其实是完全不传递height字段（因为没加在required数组里，所以字段缺失是允许的），和明确传"height": null是两回事；
• 部分API网关或Swagger工具对请求的验证会更宽松，会把null值自动当作“字段未提供”来处理，但这其实不符合严格的OpenAPI规范。

而响应的验证通常会更严格——服务端返回的内容是明确的结构化数据，当你返回"bark": null时，工具会严格校验：null不属于string类型，且nullable默认是false，所以直接抛出验证错误，这是完全符合规范的。

Properties的null值处理（未显式配置时） #

对于object类型的properties里的每个字段：

• 如果完全不传递该字段：因为没把它加入required数组，所以是合法的，属于“可选字段未提供”；
• 如果明确传递null值给该字段：因为默认nullable: false，所以违反类型规则，会触发验证错误。

additionalProperties的默认规则 #

当你没给object类型指定additionalProperties时，默认值是true：

• 这意味着允许在请求/响应中添加schema里未定义的额外字段；
• 这些额外字段的类型没有限制（包括可以是null），除非你把additionalProperties设为false（禁止额外字段），或者指定一个具体的schema（按该schema验证额外字段）。

解决你问题的方案 #

如果想要允许bark字段返回null，只需要给它显式加上nullable: true即可：

"DogResponse": {
  "type": "object",
  "properties": {
    "bark": {
      "type": "string",
      "nullable": true
    }
  }
}

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