swagger-api / swagger-api/swagger-ui

Buggy $ref behaviour in paths

Open
#10,144 1 comment 0 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

  • OS: Ubuntu 18
  • Browser and version: tested in Firefox 127.0.2 and Chrome 109.0.5414.74
  • Method of installation: npm install swagger-ui-express
  • Swagger-UI version: Tested in 4.1.2 and 5.0.1
  • Swagger/OpenAPI version: OpenAPI 3.0.2

Example Swagger/OpenAPI definition:

openapi: 3.0.2
info:
  title: Minimal example
  version: 1.0.0

paths:
  /projects:
    get:
      $ref: '#/components/schemas/ProjectsQuery'
    post:
      $ref: '#/components/schemas/ProjectsQuery'


components:
  schemas:
    ProjectsQuery:
      summary: Get a list of projects
      tags:
        - projects
      parameters:
        - name: limit
          description: number of projects
          schema:
            type: integer
            default: 10
            maximum: 100
      responses:
        200:
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    description: an array of projects

Swagger-UI configuration options:

// Library to read yaml files
const yaml = require('yamljs');
// Import the swagger logic
const swaggerUI = require('swagger-ui-express');
// Read the specification
const specification = yaml.load(`${__dirname}/description.yml`);
// Set some swagger configuration parameters
const swaggerConfig = {
    customCss: `.swagger-ui .topbar { display: none }`,
    customSiteTitle: `Minimal example`,
    swaggerOptions: {
        supportedSubmitMethods: [] // Disable all 'Try it out' buttons
    }
};
// Parse it with the Swagger logic
const swaggerSpec = swaggerUI.setup(specification, swaggerConfig);
module.exports = swaggerSpec;
Describe the bug you're encountering

When using $ref to define a path the swagger display is buggy.
It is ignoring the summary and the tags (at least) until we click on the endpoint.
Once clicked, it starts to work perfectly.

To reproduce...

Steps to reproduce the behavior:

  1. Just open it
  2. Click on the endpoint to fix de bug until we reload the page
Expected behavior

Works properly from the beginning

Screenshots

Before:
wrong

After:
less_wrong

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

Start with the provided description.yml and the shown swagger-ui-express setup, then load the OpenAPI 3.0.2 example in Swagger UI 4.1.2 or 5.0.1. Compare the initial rendering with the state after clicking an endpoint; done means the referenced path shows its summary and tags correctly before any click.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.