如何在Swagger中描述含动态唯一键的应用对象数组？

首先得澄清一点：你给出的示例其实是一个键为动态字符串的对象（用{}包裹），而非数组（数组是[]包裹）。如果是数组的话结构会是[{"Application Name 1": {...}}, ...]，但从你的示例来看应该是前者。

接下来，在Swagger（OpenAPI）里，要描述这种键名不固定、但值结构统一的对象，我们需要用到additionalProperties关键字——它专门用来定义对象中所有未被properties列出的键值对的结构。

完整的Swagger定义示例 #

definitions:
  Application:
    type: object
    properties:
      _Id:
        type: integer
      category:
        type: string
      version:
        type: string
    required:
      - _Id
      - category
      - version  # 可选，如果你想强制这些字段必须存在的话

  ApplicationMap:  # 给这个动态键对象起个名字，方便后续引用
    type: object
    additionalProperties:
      $ref: "#/definitions/Application"

关键部分解释 #

• ApplicationMap是我们定义的动态键对象类型，type: object明确它是一个JSON对象。
• additionalProperties: { $ref: "#/definitions/Application" }表示：这个对象里的所有键（不管名称是什么），对应的值都必须符合Application定义的结构。
• 如果你的API返回的就是这个ApplicationMap类型的对象，在接口的responses里直接引用即可：

  paths:
    /applications:
      get:
        responses:
          200:
            description: 所有应用的集合
            schema:
              $ref: "#/definitions/ApplicationMap"
  

如果你确实需要数组的情况 #

如果你的实际需求是“一个数组，每个元素是包含单个动态应用名称的对象”（比如[{"App1": {...}}, {"App2": {...}}]），可以这样定义：

definitions:
  ApplicationEntry:
    type: object
    additionalProperties:
      $ref: "#/definitions/Application"
  ApplicationArray:
    type: array
    items:
      $ref: "#/definitions/ApplicationEntry"

这样就能准确描述你需要的结构啦。

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