duplicate $ref object in swagger UI #7576

[Mathias02]

Content & configuration

Swagger/OpenAPI definition:

# your YAML here

components:
 schemas:
   User:
     type: object
     properties:
       id:
         type: string
       name:
         type: string
   Error:
     type: object
     properties:
       code:
         type: integer
       message:
         type: string

paths:
 /users:
   get:
     summary: Retrieve a list of users
     responses:
       200:
         description: A list of users
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/User'  # Correct usage of $ref
       400:
         description: Invalid request
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/Error'  # Different schema for error response

Swagger-UI configuration options:

SwaggerUI({
  // your config options here
url: "https://my-api.com/openapi.json",  // The path to your OpenAPI definition
 dom_id: "#swagger-ui",  // ID of the HTML container
 presets: [SwaggerUI.presets.apis],
 layout: "BaseLayout"
})

?yourQueryStringConfig

Is your feature request related to a problem?

Yes, when Swagger UI detects duplicate $ref objects, it may cause issues where the same object is rendered multiple times. This can happen if the OpenAPI specification contains duplicate references to the same schema or component, leading to confusion and rendering issues. e.g,
paths:
/users:
get:
responses:
200:
description: A list of users
content:
application/json:
schema:
$ref: '#/components/schemas/User'
400:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/User' # Duplicate $ref causing multiple renderings of the User schema

Describe the solution you'd like

The solution is to ensure that $ref references in the OpenAPI spec are unique, meaning they should not be poiting to the same definition or path in your OpenAPI specification.

1. Ensure that every $ref in the OpenAPI spec refers to a unique schema,
2. If using $ref to reference the same schema in multiple places, ensure the references are necessary or differentiate them (e.g., UserDetails vs. UserSummary).
3. Swagger UI should display schemas based on these unique references without duplication

Describe alternatives you've considered

• Using manually unique field names rather than $ref and reuse components,
• Relying on Postman for API testing instead of Swagger UI, but this would defeat the purpose of having a Swagger UI that is easy to use for front-end testing,
• Writing custom front-end logic to handle multipart/form-data or custom $ref parsing, but this requires significant additional work.

Additional context

• Tools like Swagger Editor or Speccy can help identify duplicate references in your OpenAPI spec before loading them in Swagger UI,
• This feature improvement would make it easier to maintain large OpenAPI specifications without having to manually track $ref usage