如何在 OpenAPI / Swagger 中递归引用封闭类型定义？

Posted 2023-02-16

【中文标题】如何在 OpenAPI / Swagger 中递归引用封闭类型定义？

【英文标题】：How to refer to enclosing type definition recursively in OpenAPI / Swagger?

【发布时间】：2016-08-20 08:19:46

【问题描述】：

我正在 Swagger Editor 中编写 OpenAPI 定义。

我的一个类型定义包含一个数组，其中包含与父元素相同类型的子元素。 IE。像这样：

definitions:
  TreeNode:
    type: object
    properties:
      name:
        type: string
        description: The name of the tree node.
      children:
        type: array
        items:
          $ref: '#/definitions/TreeNode'

但是，Swagger 编辑器不会在 children 数组中提取递归引用，它只是显示为“未定义”元素的数组。

有人知道怎么做吗？`

【参考方案1】：

你的定义很好。这是在 Swagger 编辑器和 Swagger UI 中呈现递归模式的一个已知问题：

https://github.com/swagger-api/swagger-ui/issues/3325

要解决“示例值”中的null/undefined 值，您可以将自定义example 添加到您的架构中：

definitions:
  TreeNode:
    type: object
    properties:
      name:
        type: string
        description: The name of the tree node.
      children:
        type: array
        items:
          $ref: '#/definitions/TreeNode'
    example:
      name: foo
      children:
        - name: bar
        - name: baz
          children:
            - name: qux