SwaggerHub如何定义属性数可变的同类型非数组嵌套对象

你需要的这种固定结构对象下挂载任意数量同类型动态键值对的场景，直接使用OpenAPI规范原生支持的additionalProperties关键字即可实现，不需要改字段类型为数组，完全匹配你要求的{}包裹JSON对象格式。

核心配置逻辑 #

additionalProperties专门用于约束对象类型下，未在properties中显式声明的所有动态属性的格式规则，配合minProperties/maxProperties还可以控制动态属性的数量范围，刚好适配address、address2、addressN这类任意数量同类型地址的需求。

具体定义示例 #

如果你在SwaggerHub使用的是当前主流的OpenAPI 3.x版本，直接按如下结构定义即可，你之前已经完成的Address结构可以直接通过$ref引用：

User:
  type: object
  required:
    - name
    - addresses
  properties:
    name:
      type: string
      example: Alex
    addresses:
      type: object
      # 约束所有动态key对应的value都是Address类型
      additionalProperties:
        $ref: '#/components/schemas/Address'
      # 强制至少有1个地址属性，可根据业务调整数值
      minProperties: 1
      # 文档示例可以写任意数量的地址，不会触发结构校验报错
      example:
        address:
          province: "Zhejiang"
          city: "Hangzhou"
          detail: "Xihu Road 123"
        address2:
          province: "Guangdong"
          city: "Shenzhen"
          detail: "Nanshan Avenue 456"
        address3:
          province: "Beijing"
          city: "Beijing"
          detail: "Chang'an Street 789"

如果你使用的是旧版Swagger 2.0（OpenAPI 2）规范，只需要调整$ref的引用路径即可：

User:
  type: object
  required:
    - name
    - addresses
  properties:
    name:
      type: string
      example: Alex
    addresses:
      type: object
      additionalProperties:
        $ref: '#/definitions/Address'
      minProperties: 1

注意事项 #

• 不要在addresses字段的properties下显式声明address、address2这类固定字段，否则会把动态属性变成固定字段，无法支持任意数量扩展
• 如果业务需要限制地址的最大数量，可在addresses下新增maxProperties字段，填入对应数值即可
• 该定义下SwaggerHub会自动识别动态属性的结构，渲染出的文档、自动生成的Mock服务都会完全匹配实际API的返回格式

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