如何在OpenAPI（Swagger）中定义接受匿名对象数组的参数？

我来帮你搞定这个问题！在OpenAPI里定义接受任意对象数组的参数，核心是利用additionalProperties关键字来描述匿名对象，再把它作为数组的items类型。下面分不同的OpenAPI版本和参数位置来详细说明，同时帮你排查Swagger Editor报错的原因。

一、OpenAPI 3.x（推荐）的写法 #

如果你的API用的是OpenAPI 3.0+规范，下面是两种常见场景的正确定义：

1. 请求体中的任意对象数组 #

这是最常见的场景，比如POST接口接受一个包含匿名对象的JSON数组：

openapi: 3.0.3
paths:
  /submit-data:
    post:
      summary: 接受任意对象数组的POST接口
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                # 定义匿名对象：允许任意属性
                type: object
                additionalProperties: true
      responses:
        '200':
          description: 数据提交成功

这里的additionalProperties: true表示这个对象可以包含任何未预先定义的属性，完全符合你要的“无需指定属性的匿名对象”需求。

2. 查询参数中的任意对象数组 #

如果是GET接口要通过查询参数传递这种数组（相对少见，但也支持），需要指定style: form和explode: true来确保参数能正确解析：

openapi: 3.0.3
paths:
  /filter-data:
    get:
      summary: 通过查询参数传递任意对象数组
      parameters:
        - name: filters
          in: query
          required: true
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
          style: form
          explode: true
      responses:
        '200':
          description: 查询成功

二、Swagger 2.0（旧版）的写法 #

如果你还在使用Swagger 2.0规范，写法略有不同：匿名对象需要用additionalProperties: {}（空Schema）来表示，同时请求体要放在parameters数组里：

swagger: '2.0'
paths:
  /submit-data:
    post:
      summary: Swagger 2.0中的任意对象数组接口
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: array
            items:
              type: object
              additionalProperties: {}
      responses:
        200:
          description: 数据提交成功

三、解决"invalid parameter definition"错误 #

你遇到的编辑器报错，大概率是以下原因之一：

• 错误的参数位置：在OpenAPI 3.x中，请求体参数不能放在parameters数组里，必须用requestBody字段定义，否则会触发参数定义无效的错误。
• 不符合版本规范：比如在Swagger 2.0里用了additionalProperties: true，或者在OpenAPI 3.x里用了in: body的写法。
• 遗漏必要字段：比如数组定义时没写items，或者对象定义时没指定type: object。

只要按照上面的示例调整你的定义，应该就能解决报错问题了。

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