如何在OpenAPI YAML中定义可接受多枚举值的查询参数？

我来帮你搞定这个sort参数的定义！你之前的写法只支持单个枚举值，没办法处理逗号分隔的多值情况，而且对空值的处理也没完全匹配需求。下面是正确的实现方式：

- name: sort
  in: query
  required: false
  description: Sort the results by attributes.
  schema:
    type: array
    items:
      type: string
      enum: [field1, field2, field3]
    nullable: true  # 允许参数值为null（对应不传或空值场景）
  style: form
  explode: false  # 关键设置：将数组序列化为逗号分隔的字符串
  allowEmptyValue: true  # 允许参数存在但值为空，比如 ?sort=

关键说明： #

• array类型+items枚举：明确参数可以接受多个枚举值的集合
• style: form + explode: false：这是实现逗号分隔多值的核心！OpenAPI会自动把数组格式化为field1,field2这样的字符串，完全匹配你的示例
• nullable: true：允许参数值为空（对应不传参数的场景，或者部分工具解析空值为null）
• allowEmptyValue: true：支持用户显式传入空值，比如?sort=这种情况

为什么你之前的写法不行？ #

你原来用type: string的枚举，只能接受单个枚举值，没办法解析逗号分隔的多个值。allowEmptyValue: true在这里只是允许参数存在但值为空，但没法处理多值场景。

这个定义在OpenAPI 3.0及以上版本都能正常工作，不管是Swagger UI展示还是后端工具解析，都会正确识别多值和空值的情况~

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