swagger-api / swagger-api/swagger-ui

Path as reference with parameters are ignored

Open
#6,931 2 comments 5 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
  • OS: Windows 10 with WSL Ubuntu, also tried in Ubuntu as VM
  • Browser: Chrome/ Firefox/ Edge
  • Version: 88.0.4324.150/ 85.0.1 /85.0.564.67
  • Method of installation: docker-container
  • Swagger-UI version: 3.41.1,gitRevision: ge538e26
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

Example Swagger/OpenAPI definition:
Main File:

...
  /users/{userId}:
    $ref: ./paths/Usermanagment/usersUserId.yaml
...

included File via ref

parameters:
  - in: path
    name: userId
    schema:
      $ref: './components/schemas.yaml#/userId'
    required: true
    description: Unique numeric ID of the user to get
    example: userid12
get:
  tags:
    - User Management
...

Swagger-UI configuration options:
No options are used, just the plain container is started with

docker run -p 80:8080 -e SWAGGER_JSON=/tmp/swagger.yaml -v $(pwd):/tmp swaggerapi/swagger-ui
Describe the bug you're encountering

If a path object is referenced the common parameters of the path are not displayed in the swagger-ui.

To reproduce...

Steps to reproduce the behavior:

  1. create a main file.
  2. Reference a path object (see above), which has common parameters for the path
  3. See the error in the swagger-ui. The parameter is not shown...
Expected behavior

The parameter is shown.

Screenshots

image

Additional context or thoughts
  1. I also tested this with redoc. He shows the parameter correctly.
  2. Also if I resolve all references in the main file via a cli tool (speccy) and create one file the parameters are shown correctly again.

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

Reproduce the issue with the main YAML file and the referenced Usermanagment/usersUserId.yaml file, using the documented Docker command. Start by tracing how Swagger UI resolves a referenced Path Item and its common parameters. Done means the userId path parameter appears in the rendered operation, while direct and fully resolved definitions continue to work.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, javascript, openapi
Domain
api, documentation, 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.