swagger-api / swagger-api/swagger-ui
Question regarding the behaviour of `allOf` and `example`
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
I was wondering what the expected behavior of allOf with example is. For example I have:
/example:
get:
summary: Example
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/MySchema'
- example:
my_string: "override"
my_array:
- "override"
components:
schemas:
MySchema
type: object
properties:
my_string:
type: string
my_array:
type: array
items:
type: string
example:
my_string: "original"
my_array:
- "original"
This results in the following example for the response:
{
"my_string": "override",
"my_array": [
"original",
"override"
]
}
Swapping the order within the allOf block results in:
{
"my_string": "original",
"my_array": [
"override",
"original"
]
}
For context, I have a Schema that I want to use in a few different response bodies. Some of these responses need certain values to be slightly different in the examples. I noticed the above behaviour and thought it would be convenient, although I want to make sure that this is expected / supported.
I'm also unsure if this is something specific to swagger-ui or if it's part of the OpenAPI spec, so apologies if I' have asked in the wrong place.
Thanks in advance :)
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
No files, tests, or entry points are mentioned. Start by comparing the observed allOf/example behavior with the OpenAPI specification, then trace how Swagger UI generates response examples; done means determining whether the merge behavior is supported and, if not, identifying the expected handling or documentation needed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100