Refer to self in OpenAPI 3.0

Question

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'

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?

Answer 1

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

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

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

Answer 2

I got tired of this pesky situation, so I went with no example at all and chose to get rid of the items property, add a description element and use an empty array instead:

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

Answer 3

You can achieve that by a proxy model:

    ...
    _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'
    ...