OpenAPI中数组作为查询参数的配置问题求助

我需要创建一个GET API，通过?status=Active,Inactive,Registered格式的查询参数（用状态数组过滤列表），但最初的OpenAPI配置无法正常工作，添加单独的status参数配置后才恢复正常，想知道遗漏了哪些配置。

最初失效的配置 #

openapi: 3.0.2
...
paths:
      /something:
        get:
          parameters:
            - in: query
              name: filter
              schema:
                $ref:  #/components/schemas/FilterValues
                explode: true
components:
  schema:
    FilterValues:
      properties:
        status:
          type: array
          $ref: "#/components/schemas/Status"
    Status:
      type: string
      enum: [Active,Inactive,Registered]
      example: "Active"

可正常运行的配置 #

openapi: 3.0.2
...
paths:
      /something:
        get:
          parameters:
            - in: query
              name: filter
              schema:
                $ref:  #/components/schemas/FilterValues
                explode: true
            - in: query
              name: status
              schema: 
                type: array
                items:
                  $ref: #/components/schemas/Status

components:
  schema:
    FilterValues:
      properties:
        ...
    Status:
      type: string
      enum: [Active,Inactive,Registered]
      example: "Active"

问题原因及修正方案 #

核心问题点 #

1. $ref使用错误：在FilterValues的status字段中，你同时声明了type: array和$ref，但OpenAPI中$ref会覆盖所有同级字段，导致type: array被忽略，该字段未被识别为数组类型。正确的数组定义应该用items指定元素的Schema。
2. 参数层级不匹配：你最初的配置把status作为filter对象的嵌套属性，对应URL格式应为?filter[status]=...，但你需要的是status作为顶级查询参数，所以单独定义status参数才符合需求。
3. 组件拼写错误：components下的节点应为复数schemas，而非单数schema，这也是配置失效的潜在原因。
4. 数组序列化规则缺失：你需要的逗号分隔格式，需要明确配置style: form和explode: false（默认explode: true会生成?status=Active&status=Inactive这种多参数格式）。

修正后的最简配置 #

如果不需要filter对象参数，直接定义status查询参数即可：

openapi: 3.0.2
...
paths:
  /something:
    get:
      parameters:
        - in: query
          name: status
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Status"
          style: form
          explode: false  # 指定逗号分隔的序列化格式
components:
  schemas:
    Status:
      type: string
      enum: [Active, Inactive, Registered]
      example: "Active"

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