swagger-api / swagger-api/swagger-ui

$ref in path method renders in default tag

Open
#5,462 2 comments 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

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

Live example: code, doc

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:

  1. Go to https://app.swaggerhub.com/apis-docs/murrayju/Bug/1
  2. Click on /api/bar
  3. 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:
image

After click:
image

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.