如何在 OpenAPI/Swagger 中递归引用封闭类型定义? [英] How to refer to enclosing type definition recursively in OpenAPI / Swagger?

问题描述

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

I'm writing an OpenAPI definition in Swagger Editor.

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

One of my type definitions contains an array containing child elements of the same type as the parent. I.e. something like this:

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

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

However, Swagger Editor doesn't pick up the recursive reference in the children array, which is simply shown as an array of "undefined" elements.

有人知道怎么做吗?`

推荐答案

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

Your definition is perfectly fine. It's a known issue issue with rendering recursive schemas in Swagger Editor and Swagger UI:

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

要解决示例值"；显示 null/"string"/undefined 而不是递归元素，您可以将自定义 example 添加到你的架构:

To work around the "Example Value" showing null/"string"/undefined instead of a recursive element, you can add a custom example to your schema:

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

这篇关于如何在 OpenAPI/Swagger 中递归引用封闭类型定义?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！