swagger-api / swagger-api/swagger-ui
Path as reference with parameters are ignored
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:
- create a main file.
- Reference a path object (see above), which has common parameters for the path
- See the error in the swagger-ui. The parameter is not shown...
Expected behavior
The parameter is shown.
Screenshots

Additional context or thoughts
- I also tested this with redoc. He shows the parameter correctly.
- 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
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
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