swagger-ui - 在 OpenAPI 3.0 中引用 self

Question

我在 OpenAPI 3.0 中有一个数据模型定义，使用 SwaggerHub 来显示 UI。我希望模型的属性之一是 related ，这是同一模型的属性数组。

    Foo:
      properties:
        title:
          type: string
        related:
          type: array
          items: 
            $ref: '#/components/schemas/Foo'

解析器似乎不喜欢这样 - UI 显示 related属性作为一个空数组。这种自引用在 OpenAPI 3.0 中是否可行？

Answer 1

您的定义是正确的，只是 Swagger UI 当前无法正确呈现循环引用定义。见 issue #3325详情。

您可以做的是添加模型 example ，并且 Swagger UI 将显示此示例，而不是尝试从定义生成示例。

    Foo:
      type: object
      properties:
        title:
          type: string
        related:
          type: array
          items: 
            $ref: '#/components/schemas/Foo'
      example:     # <-------
        title: foo
        related:
          - title: bar
          - title: baz
            related:
              - title: qux

或者，您可以添加 example只为 related大批:

    Foo:
      type: object
      properties:
        title:
          type: string
        related:
          type: array
          items: 
            $ref: '#/components/schemas/Foo'
          example:   # <--- Make sure "example" is on the same level as "type: array"
            - title: bar
            - title: baz
              related:
                - title: qux