swagger-api / swagger-api/swagger-ui
Buggy $ref behaviour in paths
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:
- Just open it
- Click on the endpoint to fix de bug until we reload the page
Expected behavior
Works properly from the beginning
Screenshots
Before:
After:
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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