Multiple responses using oneOf attribute do not appear in UI

[danr1979]

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?
Which Swagger-UI version?
How did you install Swagger-UI?
Which browser & version?
Which operating system?

Demonstration API definition

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/AuthorisationResponse'
            - $ref: '#/components/schemas/ForbiddenResponse'

Configuration (browser query string, constructor, config.yaml)

constructorConfig contains just the default values.

Expected Behavior

Since I have two schemas passed in as a $ref to the 200 response I would expect to see two schemas in the Swagger UI application.

Current Behavior

Instead I see only the reference to the 200 response and its description with no example responses displayed as JSON in the black boxes.

Possible Solution

Context

[webron]

You've left out a bunch of details from the table - please fill them in.

We also need a full API definition - we can't really test the issue with the snippet you provided.

[mrichar1]

The following spec shows nothing in the responses section of the UI - replacing the oneOf section with just an object containing either of the refs and it works fine.

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	3.0.0
Which Swagger-UI version?	3.4.2
How did you install Swagger-UI?	CDN (Cloudflare)
Which browser & version?	firefox 56/Chromium 62
Which operating system?	Linux (Ubuntu 16.04.3

openapi: 3.0.0
info:
  contact:
    email: none@example.com
    name: No Name
  description: Example API
  version: 0.0.2
  title: example
paths:
  "/test":
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - "$ref": "#/definitions/foo"
                - "$ref": "#/definitions/bar"
definitions:
  foo:
    type: string
  bar:
    type: int

[zakini]

Similar issue occurs when using oneOf for a request body.

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	3.0.0
Which Swagger-UI version?	which ever version is on editor.swagger.io
How did you install Swagger-UI?	using editor.swagger.io
Which browser & version?	Firefox 57.0
Which operating system?	macOS 10.12.6

openapi: 3.0.0
info:
  title: Test API
  version: 0.0.1
servers:
  - url: 'localhost:3000/api'
    description: Local API URL.
paths:
  /test:
    get:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/a'
                - $ref: '#/components/schemas/b'
      responses:
        '200':
          description: OK
components:
  schemas:
    a:
      type: integer
    b:
      type: string

[epetitje]

Hello,

I have the exact same problem and this issue still exists in version 3.5.

[Oleg-Arkhipov]

I would be glad to see this implemented too. In the current state using multiple responses is not really usable because documentation consumer has to dig into YAML/JSON to find out all this information.

[crussell52]

@shockey I'm confused why this has been tagged as a Feature instead of Bug. According to the Specification, schema is listed as supporting anyOf, oneOf, and allOf.

[crussell52]

Applying the oneOf to type within components/schema does not work around this problem.

components:
  responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

You can sort of work around this by declaring type: object as a sibling to oneOf:

components:
  responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            oneOf:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      type: object     # Workaround-ish
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

OR In the referenced schema component

components:
 responses:
    ...
    ServerWriteError:
      description: Write Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerWriteErrorResponse'

  schemas:
    ...
    ServerWriteErrorResponse:
      type: object
      oneOf:
        - $ref: '#/components/schemas/PartialWriteError'
        - $ref: '#/components/schemas/BaseError'

The work-around isn't great because it puts an empty object in the response example (which is shown by default), but at least consumers can see the relevant models: