swagger-api / swagger-api/swagger-ui
$ref not being rendered in response example
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: Manjaro
- Browser: Chrome
- Version: 107
- Method of installation: docker
- Swagger-UI version: v4.13.2
- Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration
The swagger content and configuration is split among multiple files, see repository github.com/ygurin/swagger-bug-demo.
The structure of the project looks like so:
.
├── Dockerfile
├── openapi
│ ├── components
│ │ ├── examples
│ │ │ └── foo
│ │ │ └── getFooResponse.json
│ │ ├── headers
│ │ │ ├── channel.yaml
│ │ │ └── key.yaml
│ │ └── schemas
│ │ └── foo
│ │ └── get-foo-response-schema.json
│ ├── openapi.yaml
│ └── paths
│ └── foo
│ └── foo.yaml
└── README.md
9 directories, 8 files
This is the main openapi.yaml file:
openapi: 3.0.0
info:
version: '1'
title: ''
description: 'Demo of a bug in swagger'
paths:
/api/foo:
$ref: 'paths/foo/foo.yaml'
points to paths/foo/foo.yaml
get:
tags:
- foo
summary: Get a list of foo
description: |
Get a list of Foo
operationId: account
parameters:
- $ref: ../../components/headers/key.yaml
- $ref: ../../components/headers/channel.yaml
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "../../components/schemas/foo/get-foo-response-schema.json"
examples:
response:
value:
$ref: "../../components/examples/foo/getFooResponse.json"
"404":
description: Not found
"410":
description: error
Describe the bug you're encountering
The $ref described in the example: does not render. Instead, it displays the $ref string.
To reproduce...
Steps to reproduce the behaviour:
- Download the repository found here
- Build the docker container
docker build -t foo:v1 . - Run the docker container
docker run --rm -p 80:8080 -e API_URL="openapi/openapi.yaml" foo:v1 - Access http://localhost/
Expected behavior
Swagger UI renders the referenced example in the response.
Screenshots

Additional context or thoughts
I'm currently using an extension in VScode called OpenAPI (Swagger) Editor. This uses a version of Swagger-UI.
It seems to render the example with no issues, see the screenshot below:

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 linked swagger-bug-demo repository using its Dockerfile and openapi/openapi.yaml, then trace Swagger UI's response example rendering for the referenced value in paths/foo/foo.yaml. Done means the referenced getFooResponse.json content is rendered as the response example instead of the $ref string.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100