如何在Swagger中表示未知键的键值对数组（网格变更场景）

这个场景太典型了——不用费劲去枚举所有可能的网格位置，用动态键值对的对象结构就能完美解决！下面分不同OpenAPI版本给你具体的实现方式：

核心思路 #

把发生变更的网格位置（比如12x21）作为对象的属性键，对应的新ID作为属性值。这种方式既简洁又灵活，完全不需要预先定义所有网格位置。

OpenAPI 3.x（推荐） #

在components/schemas里定义一个对象类型，用additionalProperties指定值的类型：

components:
  schemas:
    GridChanges:
      type: object
      description: 仅包含发生变更的网格位置及其新ID，键为网格位置（格式如"12x21"），值为新的ID引用
      additionalProperties:
        type: string  # 如果你的ID是数字类型，改成integer即可
        description: 网格单元的新ID引用

然后在接口的请求体中引用这个Schema：

paths:
  /grid/update:
    post:
      summary: 更新网格中变更的单元
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GridChanges'
      responses:
        '200':
          description: 更新成功

请求体示例 #

客户端实际发送的JSON会是这样：

{
  "12x21": "12345",
  "23x11": "87654",
  "42x01": "12987",
  "23x09": "19283"
}

OpenAPI 2.0（Swagger 2.0） #

如果还在使用旧版本，写法类似，只是Schema放在definitions下：

definitions:
  GridChanges:
    type: object
    description: 仅包含发生变更的网格位置及其新ID，键为网格位置（格式如"12x21"），值为新的ID引用
    additionalProperties:
      type: string  # 根据ID类型调整为integer或其他

进阶：校验网格位置格式（OpenAPI 3.1+） #

如果想确保客户端发送的网格位置格式符合要求（比如必须是两位数字+x+两位数字），可以用patternProperties代替additionalProperties，并加上正则校验：

components:
  schemas:
    GridChanges:
      type: object
      description: 仅包含发生变更的网格位置及其新ID，键为网格位置（格式如"12x21"），值为新的ID引用
      patternProperties:
        '^\d{2}x\d{2}$':  # 匹配两位数字+字母x+两位数字的格式
          type: string
      additionalProperties: false  # 可选，禁止不符合格式的键传入

这种方式能有效避免客户端发送无效的网格位置，让接口更健壮。

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