swagger-api / swagger-api/swagger-ui

Incorrect oneOf rendering in Swagger UI for OpenAPI 3.1.0

Open
#10,266 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

cat: rendering type: regression
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
Content & configuration

I’m generating my OpenAPI specification using SpringDoc for my Kotlin project.

I’ve noticed that when I set the OpenAPI version to 3.0.x, Swagger UI renders my responses correctly. However, with the default version 3.1.0, it does not. The differences between the 3.0.x and 3.1.x specifications are minimal, so I believe this is an issue with Swagger UI.

To verify, I also tested the 3.1.0 specification with ReDoc, and it rendered correctly.

Swagger/OpenAPI definition:

openapi: 3.1.0
info:
  title: Example
  version: 1.0.0
paths: {}
components:
  schemas:
    Mercedes:
      allOf:
        - $ref: '#/components/schemas/Car'
        - type: object
          properties:
            foo:
              type: string
      required:
        - foo
        - name
        - type
    Bmw:
      allOf:
        - $ref: '#/components/schemas/Car'
        - type: object
          properties:
            bar:
              type: string
      required:
        - name
        - type
    Car:
      type: object
      discriminator:
        propertyName: type
      required:
        - name
        - type
      properties:
        type:
          type: string
          description: Type discriminator
        name:
          type: string
    MyResponse:
      type: object
      properties:
        cars:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Mercedes'
              - $ref: '#/components/schemas/Bmw'
      required:
        - cars

Describe the bug you're encountering

This is what I get in swagger UI:

Image

To reproduce...

Paste the yaml to https://editor.swagger.io/ or https://editor-next.swagger.io/

Expected behavior

Image

3.1.0 vs 3.0.0

Image

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

Start by pasting the supplied OpenAPI 3.1.0 YAML into editor.swagger.io and editor-next.swagger.io, then compare its oneOf rendering with the 3.0.0 version shown in the issue. Use the embedded Mercedes, Bmw, Car, and MyResponse schemas to identify the rendering difference; done means the 3.1.0 response matches the expected oneOf display.

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
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.