swagger-api / swagger-api/swagger-ui

Spec with nested use of `allOf` doesn't render example request properly

Open
#10,236 2 comments 0 reactions 0 assignees View on GitHub

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:

  1. Go to https://editor-next.swagger.io/
  2. Paste the example yaml with issue from above
  3. Expand the POST /holidays/holidayEmployees endpoint
  4. Observe the example request value shown
  5. Paste the example yaml with workaround from above
  6. Expand the POST /holidays/holidayEmployees endpoint
  7. 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
image

Example request value using spec with workaround
image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.