OpenAPI 3.0.3中array[object]查询参数定义的问题求助

1. 数组元素数量限制不生效 #

你把minItems和maxItems放错位置了——这两个关键字是数组类型的约束，应该直接定义在array层级，而非嵌套在items的object里。调整后的schema结构如下：

schema:
  type: array
  minItems: 1
  maxItems: 1  # 移到array层级，限制数组最多1个元素
  items:
    type: object
    properties:
      $match:
        # ... 后续属性保持不变

2. Swagger UI编码格式不符合预期 #

当前用content: application/json的方式会导致Swagger UI把数组元素序列化为字符串包裹的JSON，和业务代码处理逻辑不匹配。改用直接定义schema+指定序列化风格的方式：

• 移除content块，直接用schema定义数组结构
• 添加style: form和explode: false，让Swagger UI生成和JSON.stringify()输出一致的参数值。

调整后的参数定义片段：

parameters:
  - in: query
    name: find
    schema:
      type: array
      minItems: 1
      maxItems: 1
      items:
        type: object
        properties:
          $match:
            type: object
            description: 指定过滤结果的条件
            properties:
              name:
                type: string
                description: 目标导入项的名称，支持精确匹配`{"name": "item-name"}`或多值匹配`{"name": {"$in": ["name-1","name-2"]}}`
    style: form
    explode: false

3. 属性描述不展示 & 提供填写提示 #

解决描述不显示问题 #

把嵌套的object schema抽离到components/schemas中，Swagger UI会自动展示每个属性的描述。同时确保每个属性的description定义正确。

添加填写提示 #

在属性里添加example字段，直观展示不同匹配格式的用法，用户在Swagger UI里能直接看到示例。

完整优化后定义示例：

components:
  schemas:
    MatchCondition:
      type: object
      description: 指定过滤结果的条件
      properties:
        name:
          type: string
          description: 目标导入项的名称，支持精确匹配或多值匹配
          examples:
            精确匹配:
              value: "item-name"
            多值匹配:
              value: {"$in": ["name-1", "name-2"]}
    FindQuery:
      type: array
      minItems: 1
      maxItems: 1
      items:
        type: object
        properties:
          $match:
            $ref: '#/components/schemas/MatchCondition'

paths:
  /your-api-path:
    get:
      parameters:
        - in: query
          name: find
          schema:
            $ref: '#/components/schemas/FindQuery'
          style: form
          explode: false
          description: 过滤查询条件，格式为包含单个匹配对象的数组

调整后Swagger UI会：

• 展示name属性的描述和示例
• 正确限制数组仅能添加1个元素
• 生成符合预期的参数编码格式，可正常反序列化

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