swagger-api / swagger-api/swagger-ui
$ref in path method renders in default tag
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
Q&A (please complete the following information)
- OS: [linux]
- Browser: [chrome, firefox]
- Version: [latest?]
- Method of installation: [npm, also swagger.io]
- Swagger-UI version: [3.23.0]
- Swagger/OpenAPI version: [OpenAPI 3.0]
Content & configuration
Example Swagger/OpenAPI definition:
openapi: 3.0.0
info:
version: '1'
title: ''
description: 'Demo of a bug in swagger'
# Added by API Auto Mocking Plugin
servers:
- description: SwaggerHub API Auto Mocking
url: https://virtserver.swaggerhub.com/murrayju/Bug/1
definitions:
parameters:
sessionId:
type: string
in: path
name: sessionId
description: ID of the session.
required: true
paths:
/api/foo:
post:
summary: Foo
description: |
Does foo stuff
tags:
- Cat
responses:
200:
description: Successful request
/api/bar:
post:
$ref: '#/paths/~1api~1foo/post'
Swagger-UI configuration options:
Irrelevant (defaults)
Describe the bug you're encountering
The path definition that uses $ref renders in the default tag initially. Clicking on it (as if to expand) in the UI causes it to jump into the correct tag group.
To reproduce...
Steps to reproduce the behavior:
- Go to https://app.swaggerhub.com/apis-docs/murrayju/Bug/1
- Click on
/api/bar - See UI jump to a new category
Expected behavior
The path should derive the correct tags from the reference at startup, and render in the correct tag group(s) initially.
Screenshots
Initial load:

After click:

Additional context or thoughts
This is a simplified (minimal) reproduction of the bug. The real use case involves mostly similar routes, but with different path parameters. The idea is to define the endpoint definition once, and use a $ref to duplicate, along with allOf to override the parameters. Everything is working except for this weird UI glitch.
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 linked SwaggerHub reproduction and the minimal OpenAPI definition, especially the /api/bar path reference to /api/foo. Reproduce the initial load and click behavior; done means the referenced path derives its tags at startup and appears in the correct tag group without requiring a 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