Spring Boot中OpenAPI4J校验含必填字段的可空对象问题

问题分析 #

你需要实现的校验逻辑是：foo字段必须存在，且值仅允许两种情况：

• 为null
• 是包含必填bar字段的完整Foo对象

现有Schema写法导致foo: null校验失败，核心原因是nullable: true与oneOf的组合逻辑不符合预期：openapi4j会将null值代入oneOf中的Foo分支校验，而Foo是object类型且要求必填bar，null显然不满足该条件，因此抛出"Field 'bar' is required"错误。

修正后的Schema #

调整foo字段定义，将null明确作为oneOf的一个分支，同时移除冗余的nullable配置：

openapi: 3.0.3
...
paths:
...
  some/path:
    put:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - foo
              properties:
                foo:
                  oneOf:
                    - type: null  # 明确允许null值作为合法选项
                    - $ref: '#/components/schemas/Foo'
...
components:
  schemas:
    Foo:
      type: object
      additionalProperties: false
      required:
        - bar
      properties:
        bar:
          type: integer
          nullable: false  # 明确禁止bar为null

验证各测试场景 #

允许通过的请求 #

1. foo为null：

{
  "foo": null
}

2. foo为符合要求的Foo对象：

{
  "foo": {
    "bar": 1
  }
}

校验失败的请求 #

1. 未设置foo（违反根对象required: [foo]规则）：

{}

2. foo为空对象（不符合Foo的必填字段要求）：

{
  "foo": {}
}

3. bar为null（违反bar的类型与非空约束）：

{
  "foo": {
    "bar": null
  }
}

关键说明 #

• OpenAPI 3.0的nullable: true是对字段值的补充允许，但与oneOf联用时，校验器会尝试将null匹配oneOf的所有分支，引发歧义。
• 在oneOf中明确添加type: null分支，能让校验器清晰识别两种合法情况，避免逻辑冲突。
• 移除Foo的nullable: true，确保Foo对象本身不能为null，完全匹配你的需求场景。

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