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:

swagger-ui/src/core/plugins/json-schema-5/components/model.jsx

Lines 66 to 86 in 507a3bf

	/*
	* If we have an unresolved ref, get the schema and name from the ref.
	* If the ref is external, we can't resolve it, so we just display the ref location.
	* This is for situations where:
	* - the ref was not resolved by Swagger Client because we reached the traversal depth limit
	* - we had a circular ref inside the allOf keyword
	*/
	if ($ref) {
	const refName = this.getModelName($ref)
	const refSchema = this.getRefSchema(refName)
	if (Map.isMap(refSchema)) {
	schema = refSchema.mergeDeep(schema)
	if (!$$ref) {
	schema = schema.set("$$ref", $ref)
	$$ref = $ref
	}
	} else if (Map.isMap(schema) && schema.size === 1) {
	schema = null
	name = $ref
	}
	}

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?