在 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

或者，您可以只为 related 数组添加一个 example：

    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

Answer 2

我厌倦了这种讨厌的情况，所以我根本没有示例，而是选择删除项目属性，添加描述元素并改用空数组：

Foo:
  type: object
  properties:
    title:
      type: string
    related:
      type: array
      description: Array of Foo elements
      example: []

Answer 3

您可以通过代理模型实现：

    ...
    _MessageProxy:
      description: Message
      type: object
      required:
        - id
        - user
        - body
        - publishedAt
      properties:
        id:
          title: Message id
          type: string
          readOnly: true
          example: '595f4acf828b0b766ad11290'
        user:
          $ref: '#/components/schemas/User'
    Message:
      allOf:
        - $ref: '#/components/schemas/_MessageProxy'
        - type: object
          properties:
            parent:
              title: Parent
              readOnly: true
              allOf:
                - $ref: '#/components/schemas/_MessageProxy'
    ...

Answer 4

使用虚拟模型和交叉引用：

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

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

在 OpenAPI 3.0 中引用 self

Refer to self in OpenAPI 3.0

swagger-ui

openapi