OpenAPI 3.0中如何指定允许空值的表单参数？

OpenAPI 3.x将2.0版本的in: formData参数迁移到requestBody的媒体类型Schema中，但JSON Schema并没有定义和allowEmptyValue直接对应的属性。针对这个问题，有以下几种可行的解决方案：

1. 用JSON Schema语法明确允许空值类型 #

表单提交的空值通常有两种形式：null 或空字符串。你可以通过nullable关键字结合anyOf来覆盖这两种场景，严格符合JSON Schema规范：

openapi: 3.1.0
info:
  title: Brick Owl
  version: v1
paths:
  /collection/update:
    post:
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                lot_id: {}
                quantity: {}
                price:
                  type: number
                  nullable: true
                  anyOf:
                    - type: number
                    - type: string
                      enum: [""]
              required:
              - lot_id

• nullable: true 允许参数值为null
• anyOf 中的字符串枚举[""] 允许参数提交空字符串

如果只需要允许其中一种空值形式，可以简化配置（比如只允许null就保留nullable: true，去掉anyOf部分）。

2. 使用扩展属性x-allowEmptyValue #

虽然属于自定义扩展，但大部分OpenAPI生态工具（如Swagger UI、代码生成器）都支持这个属性，能直接对应2.0版本allowEmptyValue的语义，迁移成本最低：

openapi: 3.1.0
info:
  title: Brick Owl
  version: v1
paths:
  /collection/update:
    post:
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              properties:
                lot_id: {}
                quantity: {}
                price:
                  type: number
                  x-allowEmptyValue: true
              required:
              - lot_id

方案选择建议 #

• 若需要严格遵循JSON Schema标准，优先选择第一种方案，明确定义允许的空值类型；
• 若追求快速迁移、兼容旧工具或保留原语义，第二种扩展属性方案更高效。

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