swagger-ui icon indicating copy to clipboard operation
swagger-ui copied to clipboard

Buggy $ref behaviour in paths

Open d-beltran opened this issue 1 year ago • 1 comments

  • 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

d-beltran avatar Sep 23 '24 15:09 d-beltran

confirmed on latest: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/heldersepu/hs-scripts/master/swagger/10144.yaml

@d-beltran if you want some workaround you could try setting docExpansion=full: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/heldersepu/hs-scripts/master/swagger/10144.yaml&docExpansion=full

it seems that docExpansion triggers the "refresh" on the components

heldersepu avatar Oct 11 '24 12:10 heldersepu