Swagger生成时如何正确引用同一Schema下的自引用对象

问题原因 #

你当前的配置存在两处不符合OpenAPI规范的错误，直接导致subAccounts字段解析失败：

• 数组类型的引用位置错误：数组类型的元素类型定义必须放在items字段下，直接将$ref与type: array同级属于无效配置，解析器会直接跳过该字段的无效定义
• 引用路径拼写错误：Schema的根路径是#/components/schemas（schemas为复数形式），你写的路径少了末尾的s，会导致引用无法定位到目标Schema

OpenAPI原生支持同Schema的递归自引用，不需要额外做特殊适配，只要按照规范书写即可正常解析，不会触发循环引用报错。

正确配置示例 #

components:
  schemas:
    Account:
      type: object
      properties:
        name:
          type: string
        # 其余基础属性按原有规则编写即可
        subAccounts:
          type: array
          description: 子账户列表
          items:
            $ref: '#/components/schemas/Account'

配置注意事项 #

• 数组本身的属性（比如description、minItems、maxItems、uniqueItems）需要和type: array同级编写，不要放到items节点内部
• 之前添加description后字段仍为空，本质是引用位置错误、路径拼写错误两个问题导致的，和description属性本身无关
• 这种自引用写法支持任意层级的嵌套解析，Swagger UI、各语言的SDK生成工具都可以正常识别递归结构，不需要额外拆分Schema。

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