如何在Swagger的YAML中创建相同类型对象的嵌套数组结构

问题原因 #

你当前的YAML写法存在两处不符合OpenAPI Schema规范的错误，是导致解析空白的核心原因：

1. 直接将Asset定义为数组类型，结构逻辑错误：树状嵌套的核心是「单个节点包含子节点数组」，需要先定义单个Asset节点的对象结构，再在节点内声明子节点数组字段
2. 语法缺失：items字段后需要紧跟完整的schema定义，你在items后直接写属性字段，缺少type: object和properties层的包裹，属于语法错误，Swagger解析器遇到非法结构会直接跳过渲染。

正确示例代码 #

components:
  schemas:
    Asset:
      # 顶层先定义单个资产节点的对象结构
      type: object
      properties:
        id:
          type: string
        serial:
          type: number
        # 子资产字段，类型为数组，每一项都是单个Asset节点
        childAssets:
          type: array
          items:
            $ref: '#/components/schemas/Asset'

如果你需要保留子节点字段名为Asset也可以，只要确保顶层schema定义的是单个对象结构即可。

额外注意 #

部分旧版本Swagger UI对递归自引用结构的渲染支持存在缺陷，如果修改后仍有显示异常，可将Swagger UI升级到4.x及以上版本，即可正常展开多层嵌套结构。

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