OpenAPI 3.1 self-referential array items renders as array<any> and shows only raw $ref URL

[atsuoishimoto]

Content & configuration

Example Swagger/OpenAPI definition:

openapi: 3.1.0
info:
  title: test
  description: test
  version: 1.0.0
servers:
  - url: http://localhost:5000
    description: test

paths:
  /api/user:
    get:
      summary: get user
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        friends:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/User'
            required:
              - id

Swagger-UI configuration options:

SwaggerUI({
  url: "/schema.yaml",
  dom_id: '#swagger-ui'
})

Is your feature request related to a problem?

Expanding the attached OpenAPI 3.1.0 User schema in Swagger UI results in the friends property (an array that self-references User) being displayed as array, and the UI shows only a raw $ref-like string such as:

$ref=http://localhost:5000/schema.yaml#/components/schemas/User

The property definition is not expanded.

Figure 1. The self-referential property is rendered as the $ref schema name.

Describe the solution you'd like

The friends array should render as an array of User objects with the schema expanded (e.g., array<User>).

Additional context

With OpenAPI 3.0.0, a similar schema defined using allOf expands correctly in Swagger UI (see below). Under OpenAPI 3.1.0, the allOf-based definition is not usable because it triggers an error in Swagger UI 5.28.0 (#10583).

openapi: 3.0.0
info:
  title: test
  description: test
  version: 1.0.0
servers:
  - url: http://localhost:5000
    description: test

paths:
  /api/user:
    get:
      summary: get user
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        friends:
          type: array
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/User'
              - type: object
                required:
                  - id

Figure 2. The self-referential property defined with allOf is correctly expanded(OpenAPI 3.0).

[Yashsingh045]

Hi @atsuoishimoto , I'd like to work on this. Could you please assign it to me?

[glowcloud]

Hi @Yashsingh045,

I've assigned you to the issue, feel free to work on it.

For context, both in OpenAPI 2.0/3.0 dereferencing (handled by Swagger Client), and in OpenAPI 3.1 dereferencing (handled by ApiDOM), the dereferencing mechanism stops if a circular reference is detected. This is the intended behaviour.

In Swagger UI, for OpenAPI 2.0/3.0, if a schema was not dereferenced and still has the $ref available, we try to extract the referenced schema without running the dereference mechanism again. The relevant code is here: https://github.com/swagger-api/swagger-ui/blob/507a3bfe5c402f27a378d7fb8e2bb1446604b006/src/core/plugins/json-schema-5/components/model.jsx#L66-L86

For OpenAPI 3.1, we use a separate rendering plugin with the JSON Schema 2020-12 renderer. If possible, a similar mechanism could be implemented there.

[Afraar99]

Hi @glowcloud I'd like to work on this issue. Could you please assign it to me?

[MichakrawSB]

Hi @Yashsingh045, @Afraar99,

thank you both for your interest and willingness to contribute! We really appreciate it.

Just a quick update: there’s already a PR open for this issue - https://github.com/swagger-api/swagger-ui/pull/10612 - and it’s currently in our review queue.

If you’d like to help further, feel free to review the PR and share your feedback. Also, please check out other open issues — your contributions and insights are always welcome!

Cheers, Swagger Team