swagger-api / swagger-api/swagger-ui
Spec with nested use of `allOf` doesn't render example request properly
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: Windows
- Browser: Chrome
- Version: 131.0.6778.87
- Method of installation: pnpm
- Swagger-UI version: 5.18.2
- Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration
Example Swagger/OpenAPI definition:
Example yaml with issue:
openapi: 3.0.0
info:
title: spec with issue
version: 1.0
paths:
/holidays/holidayEmployees:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/HolidayEmployee"
required: true
responses:
"200":
description: success
components:
schemas:
HolidayWorker:
properties:
holiday:
type: string
example: Christmas
HolidayEmployee:
required:
- employee
type: object
allOf:
- $ref: "#/components/schemas/HolidayWorker"
properties:
employee:
allOf:
- $ref: "#/components/schemas/Employee"
- properties:
relationship:
enum:
- Self
example: Self
Employee:
required:
- lastName
type: object
allOf:
- $ref: "#/components/schemas/Person"
Person:
type: object
properties:
firstName:
type: string
example: Santa
lastName:
type: string
example: Claus
Example yaml with workaround:
openapi: 3.0.0
info:
title: spec with workaround
version: 1.0
paths:
/holidays/holidayEmployees:
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/HolidayEmployee"
required: true
responses:
"200":
description: success
components:
schemas:
HolidayWorker:
properties:
holiday:
type: string
example: Christmas
HolidayEmployee:
required:
- employee
type: object
properties:
employee:
allOf:
- $ref: "#/components/schemas/Employee"
- properties:
relationship:
enum:
- Self
example: Self
allOf:
- $ref: "#/components/schemas/HolidayWorker"
Employee:
required:
- lastName
type: object
allOf:
- $ref: "#/components/schemas/Person"
Person:
type: object
properties:
firstName:
type: string
example: Santa
lastName:
type: string
example: Claus
Swagger-UI configuration options: nothing special in particular, it's reproducible at https://editor-next.swagger.io/
Describe the bug you're encountering
When using a yaml definition such as the one provided above, the rendered example value for the request doesn't display all of the example values. In the example yaml with issue, note that the schema HolidayEmployee uses the allOf keyword and then also has a property employee that uses allOf, which in turn is referencing Employee, which uses the allOf keyword to reference Person.
When HolidayEmployee is defined in this order, in the example value for the POST /holidays/holidayEmployees endpoint, firstName and lastName properties from the Person schema are missing. If HolidayEmployee is instead defined like in the yaml work workaround example, with the properties defined before using the allOf keyword, then the example value shown by SwaggerUI shows all of the values.
To reproduce...
Steps to reproduce the behavior:
- Go to https://editor-next.swagger.io/
- Paste the example yaml with issue from above
- Expand the
POST /holidays/holidayEmployeesendpoint - Observe the example request value shown
- Paste the example yaml with workaround from above
- Expand the
POST /holidays/holidayEmployeesendpoint - Observe the example request value shonw
Expected behavior
Expect the displayed example request value to look the same regardless of the order in which allOf and properties are defined.
Screenshots
Example request value using spec with issue
Example request value using spec with workaround
Additional context or thoughts
Although I've shown a workaround by reordering how the schema is defined, this isn't a viable workaround in our actual application because the spec we're displaying is generated in a way that we do not have control over. Since the definition is valid either way, we would expect the displayed example value to be the same in both cases.
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 in editor-next.swagger.io using the two YAML definitions and compare the POST request examples. Then locate the request-example rendering path for nested allOf schemas and verify that firstName, lastName, holiday, employee, and relationship appear regardless of declaration order.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100