swagger-api / swagger-api/swagger-ui

reference name is not displayed in OpenApi 3.1.0 renderer

Open
#9,540 9 comments 13 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A
  • OS: macOS
  • Browser: chrome
  • Version: 121.0.6167.139
  • Method of installation: dist, cloud
  • Swagger-UI version: any recent version, (checked from 5.2 to 5.10.3)
  • Swagger/OpenAPI version: 3.1.0

A simple example Swagger/OpenAPI definition:

openapi: 3.0.3
info:
  title: Example
  version: 0.0.1
paths:
  /api/v1/example:
    get:
      operationId: example
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Node'
components:
  schemas:
    Node:
      required:
      - id
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NodeId'
        name:
          type: string
        parentId:
          $ref: '#/components/schemas/NodeId'
    NodeId:
      type: integer
      description: Internal ID of a Node
      format: int32
Describe the bug you're encountering

When switching openapi: 3.0.3 to 3.1.0 renderer no more displays references with their names.

Expected behavior

Referenced types are shown with their name so it's easy to see reused components

To reproduce...

Use a provided example and compare results between 3.0.3 and 3.1.0

Actual behavior

Referenced types are inlined without name (e.g. NodeId in provided simple example) - hard to see common components when using complex schemas.

Screenshots
Screenshot 2024-01-31 at 14 25 49 Screenshot 2024-01-31 at 14 25 06

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Load the provided YAML example in the Swagger UI renderer and compare the displayed schemas for OpenAPI 3.0.3 and 3.1.0, focusing on the NodeId references. The work is done when referenced types retain their component names in the 3.1.0 renderer as they do in 3.0.3.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.