swagger-api / swagger-api/swagger-ui
OpenAPI 3.0: references defined in examples should not be dereferenced
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
When defining a reference inside of examples fields on various spec objects, instead of the Example Object, the reference should not be dereferenced.
For this specification:
responses:
ExampleResponse:
description: An error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ExampleModel'
examples:
$ref: '#/components/examples/tshirt'
examples:
tshirt:
summary: Sample T-shirt data
value:
# Example value starts here
id: 17
name: T-shirt
description: 100% cotton shirt
categories: [clothes]
when the example gets dereferenced, each field of tshirt will be seen as a separate example. Each of them will be rendered as an option for examples select:
This does not happen for OpenAPI 3.1:
Additional context or thoughts
To fix this, we need to utilise ApiDOM for OpenAPI 3.0.
Originally reported by @glowcloud
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 by reproducing the issue with the OpenAPI 3.0 YAML example in this report and compare it with the OpenAPI 3.1 behavior. Trace the OpenAPI 3.0 dereferencing path and investigate how ApiDOM can preserve the reference as one Example Object. Done means the referenced example renders as a single selectable example rather than separate fields.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100