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

Question

我正在Swagger Editor中编写OpenAPI定义。我的某个类型定义包含一个数组，其中包含与父级相同类型的子元素。即类似于这样的东西：

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

然而，Swagger Editor无法识别children数组中的递归引用，它只会简单地显示为一系列"undefined"元素的数组。

有人有想法如何解决这个问题吗？

- Morten E. Rasmussen

Answer 1

您的定义完全正确。在Swagger Editor和Swagger UI中呈现递归模式的已知问题，可以通过在架构中添加自定义示例来解决“示例值”显示null/"string"/undefined而不是递归元素：

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

为了解决这个问题，您可以向您的模式添加自定义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

- Helen