在OpenAPI 3.0中引用self [英] Refer to self in OpenAPI 3.0

问题描述

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

I have a data model definition in OpenAPI 3.0, using SwaggerHub to display the UI. I want one of the properties of a model to be related, which is an array of properties of the same model.

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

解析器似乎不喜欢这样-UI将related属性显示为空数组.这种自引用是否可以在OpenAPI 3.0中使用?

The parser doesn't seem to like this - the UI shows the related property as an empty array. Is this kind of self-reference possible in OpenAPI 3.0?

推荐答案

您的定义正确，只是Swagger UI当前无法正确呈现循环引用的定义.有关详细信息，请参见问题#3325 .

Your definition is correct, it's just Swagger UI currently does not render circular-referenced definitions properly. See issue #3325 for details.

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

What you can do is add a model example, and Swagger UI will display this example instead of trying to generate an example from the definition.

    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

或者，您可以为related数组添加example:

Alternatively, you can add an example just for the related array:

    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

这篇关于在OpenAPI 3.0中引用self的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！