如何在OpenAPI中定义仅允许为空或不存在的查询参数？

OpenAPI规范中的allowEmptyValue属性支持查询参数不带值传递，比如官方给出的示例配置：

parameters:
  - in: query
    name: metadata
    schema:
      type: boolean
      allowEmptyValue: true

这种配置允许/?metadata、/?metadata=true、/?metadata=false三种请求形式，但无法满足「参数存在即视为true，不存在则为false」的需求——我们需要的是仅允许两种合法请求：

• /?metadata：metadata值为true（开启）
• /?：metadata值为false（关闭）
  并且只要参数存在，无论它附带什么值（比如/?metadata=false、/?metadata=0），都要视为true。

实现方案 #

要达到这个效果，不能直接使用布尔类型的参数配置，需要通过以下方式定义：

parameters:
  - in: query
    name: metadata
    schema:
      type: string
      enum: []  # 空枚举限制参数不能携带任何有效值
    allowEmptyValue: true
    required: false

配置说明 #

• type: string + 空enum：确保参数无法携带任何有效值，只能以无值的形式出现（即/?metadata）
• allowEmptyValue: true：允许参数不带值传递
• required: false：参数可以不存在，对应「关闭」（false）的逻辑

后端业务逻辑需要额外处理：只要请求中存在metadata参数（无论其值是什么），就将其映射为true；参数不存在时则映射为false。

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