swagger-ui: Multiple responses using oneOf attribute do not appear in UI

any news from maintainers regarding this issue?

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:

Another “workaround” is to use ReDoc instead of swagger-ui.

I agree with Tamriel, this ticket has been open since 23rd Oct 2017 so this obviously isn’t a high priority for the swagger guys. This is preventing many of us from being able to use swagger for real projects with real clients.

@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.

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.

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

Swagger ui should generate multiple examples for nested combined schemas as well.

For example:

openapi: 3.0.3
info:
  title: title
  version: 0.0.0
paths:
  /test:
    post:
      summary: test
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nested'
      responses:
        200:
          description: OK
      operationId: test.post
components:
  schemas:
    nested:
      type: object
      properties:
        some: 
          type: string
        nestedProp:
          type: object
          anyOf:
            - $ref: '#/components/schemas/one'
            - $ref: '#/components/schemas/two'
    one:
      title: One
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: ^one$
      example: 
        name: one
    two:
      title: Two
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: ^two$
      example:
        name: two

is rendered like: and should be rendered like:

openapi: 3.0.3
info:
  title: title
  version: 0.0.0
paths:
  /test:
    post:
      summary: test
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/nested'
            examples:
              nested_One:
                $ref: '#/components/examples/nested_One'
              nested_Two:
                $ref: '#/components/examples/nested_Two'
      responses:
        200:
          description: OK
      operationId: test.post
components:
  examples:
    nested_One:
      value: 
        some: string
        nestedProp:
          name: one
    nested_Two:
      value:
        some: string
        nestedProp:
          name: two
  schemas:
    nested:
      type: object
      properties:
        some: 
          type: string
        nestedProp:
          type: object
          anyOf:
            - $ref: '#/components/schemas/one'
            - $ref: '#/components/schemas/two'
    one:
      title: One
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: ^one$
      example: 
        name: one
    two:
      title: Two
      type: object
      required:
        - name
      properties:
        name:
          type: string
          pattern: ^two$
      example:
        name: two

Almost 3 yrs later. This is still an issue for me in the SwaggerUI. any update about a fix in the UI rendering?.

<Similar update to https://github.com/swagger-api/swagger-ui/issues/2651#issuecomment-488335500 for those of you who follow both tickets>

Everyone, some good news on this ticket (at last!). We’ve been working on a solution for oneOf rendering over the last couple of weeks, and are in the final stages of reviewing the changes, making sure they will work well with the try it out functionality and provide all the needed functionality.

There’s a tiny gotcha - we’re also working on a facelift for the existing UI, taking in a lot of the feedback we’ve received over the years and giving you a nicer looking, more functional product. The design of this solution is based on that facelift (more information on it will be available in the README in the upcoming weeks).

The good news is that we’re not going to wait for the facelift work to be done before implementing it, but rather to the best of our ability back port the functionality into the current design.

We hope to share mocks with you as soon as next week (but might be delayed another week) and look forward to seeing your feedback. When we share the mocks, I’ll do my best to explain how support for anyOf and not will also be added (on top of oneOf), and why solution in ReDoc (which is a very nice solution) doesn’t fit our use case. The implementation itself will come after the multiple examples support (#2651) is done, but is prioritized high right after it.

We understand how frustrating it’s been waiting for the implementation, and appreciate the patience, feedback and support from everyone. This is a matter of weeks now (and not referring to hundreds or dozens of those, much much less 😉).

Folks: per the Swagger Contribution Guide, please refrain from making comments that only serve to bump the issue or indicate interest — use Reactions to vote for issues instead, since we use them to sort issues based on user interest.

Thanks!

No ETA for this yet? More than 2 years after first issue opened…

Are there any updates from Swagger team regarding this functionality?

Similar issue occurs when using oneOf for a request body.

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

Seriously wonder why the pull request still has no official response from the maintainers of this project even though it’s been there for months. Please look at it 😢 . A lot of people are waiting on this.

Waiting for this

considering the website of SwaggerUI claims “Complete OAS Support Complete OAS Support Visualize APIs defined in Swagger 2.0 or OAS 3.0” (https://swagger.io/tools/swagger-ui/) and oneOf, anyOf and allOf are clearly part of openApi 3, this should thus be re-categorized as a Bug, or the softwares description be corrected.

I’m facing the same issue, can anybody tell me if they have found a workaround to see the examples as well?

Hi,

have the same problem here. Downloaded the current master branch of swagger ui, but the example rendering, while using oneOf, still does not work.

Would be nice, if there will be a fix soon. Maybe someone knows a workaround or something else?

Thanks, Nils.

+1

Hello,

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

@webron is there anything we can do to help you to get this issue fixed? Is there a BountySource account for swagger-ui / anyone willing to implement this? We would be happy to chip in…

Hello, people. The same is happening to me today. I just came to give you soulish support

👋 the is a workaround I’ve found working and built a simple demo: https://gitlab.com/alecnmk/openapi-swaggerui-multiple-response-examples-demo/-/blob/main/openapi.yaml#/default/get_products__id_

If I can add my 2c here, I think it would be nice to have a select component with all the possible models, and as each one is selected it can show the example and model in the same way. It gives the power to map multiple responses schemas and the user can inspect each one a time. The same could be said about request body, should I file another issue?

Any news about this issue?

Still a problem, new to Swagger so it could be a YAML structure problem. However, if I have a requestBody that can contain a key of params and those params could be oneOf many different schemas, the entire thing is useless since the examples do not show.

Any updates?

Another “workaround” is to use ReDoc instead of swagger-ui.

Guys I want to suggest you try to use examples as workaround

content: 
  application/json: 
    schema: 
      anyOf: 
        - $ref: '#/components/schemas/Jessica' 
        - $ref: '#/components/schemas/Ron'
 examples: 
  Jessica: 
    value: 
      id: 10 
      name: Jessica Smith 
  Ron: 
    value: 
      id: 20 
      name: Ron Stewart 

For those of you who didn’t notice, @PavelStefanov has submitted #3803 as a potential solution for this feature.

Everyone’s input on this one has been great and much appreciated. Looks like @mikefidel managed to cover the major concerns I’ve been having all along. Let’s try to summarize this and see how to proceed.

For clarity - this issue is relevant for OAS3 (and later) only.

The issue of displaying examples comes in several places:

• Parameters (since they now support schema)
• RequestBody (as a replacement to body parameters)
• Responses
• Headers (just like parameters)

While the two obvious places are responses and request body, we cannot ignore the other two places. The solution needs to fit all, otherwise we risk pushing the problem down the line.

The parameters and request bodies representation should also fit into the try-it-out functionality, meaning it should serve as an easy way to provide the input.

The issue also comes in two forms:

• Generating examples when none are provided by the user (which is this ticket).
• Displaying multiple examples when they are provided by the user (This is trying to be covered by #4092, which is based on #3616).

These two are related, because we would display one or the other, but not both. The experience should be similar as they serve the same purpose - showing an API consumer what they’re expected to send/receive to/from the API.

anyOf and oneOf (and allOf for that matter) - aren’t very meaningful when it comes to documentation (not functionality). We shouldn’t assume that a consumer of the documentation automatically understands JSON Schema just because it’s what the specification supports. The example in #4368 shows this problem exactly - it contains a oneOf of 4 items, but if you look at the generated examples, you’d notice that providing the last of the 4 as a value - it would actually fail, because it conflicts with the first one. This kind of distinction would be difficult on consumers to understand simply by seeing oneOf at the top of the examples. (for those of you who missed it - the last option would also validate against the first schema - this means it does not fit just one of the schemas and so it would fail validation. This wouldn’t be the case with anyOf.) Similarly - allOf does not mean merge.

@mikefidel brought up the biggest issue that concerns me - having anyOf/oneOf deeper in definitions, and not just directly under scheme - that’s where things get really nasty, and at the moment I’m not sure there’s a clean solution to that.

It does seem that at the moment the majority of users is interested in supporting oneOf/anyOf at the root of the schema simply to be able to describe different basic input/output options. We could say that for the immediate future we’ll try to add support for those cases and punt on supporting the deeper nested cases - I’m ok with that.

For input - I tend to favor either a tabbed view or a drop-down, where the user can choose which one they want to be displayed and served as a baseline for input. For output - we can go with either that or a flat view as proposed in the PR. The down side of a flat view is that it can make the UI very ‘long’. On the other hand, it’s easier to view all the information. The downside of a tabbed view is dealing with many examples that don’t necessarily fit the view, and then you have another scroll-like feature to move between the different tabs.

It’s a bit of a long summary, but I hope this has given you some insight into the challenges in supporting this feature. I’m sure any individual would love to see something that supports their use case, but it is our challenge, as project maintainers, to address the community as a whole. We’d appreciate your input and feedback on this based on the summary. I will try to get a UX person involved in this as well, but any additional input you may have will help.

encountered same issue, and our APIs use a 200 status code with an inner status that indicates error and success… so I need to display to the user the vsrious use cases and cannot do this. It would be great if it gets fixed.

In case something want a build in the meanwhile: https://github.com/eLvErDe/swagger-ui/releases

It’s working perfectly fine with my Python module, dist folder include built js/css, based on 3.24.3 tag with only PR #5530 included.

@Moro-Code no promises on an ETA, but this is currently the next major item for the core team to address 😄

https://github.com/swagger-api/swagger-ui/issues/2651#issuecomment-506982837 is solved now, so there’s nothing blocking us from working on it!

i`m facing the same issue

This issue should have been solved https://github.com/swagger-api/swagger-ui/issues/5435#event-8668317571

+1 to this - My scenario: API client should expect return to contain array of objects who’s underlying structure changes based on type fields that are optional query params.

Disregard above - I found a solution with current version:

  responses:
    '200':
      description: search results matching criteria
      content:
        application/json:
          schema:
            type: array
            items:
              oneOf:
                - $ref: '#/components/schemas/foo'
                - $ref: '#/components/schemas/bar'

I am having a similar issue here. See below an example spec in which I am attempting to describe a form which can accept one of two possible schemas:

openapi: 3.0.1
info:
  title: FooBar
  version: 1.0.0
paths:
  /foobar:
    post:
      summary: Summary
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
              - type: object
                properties:
                  Foo:
                    type: string
              - type: object
                properties:
                  Bar:
                    type: string
      responses:
        default:
          description: Description

Please note that the same issue occurs when using a requestBody/content type of multipart/form-data

This endpoint should expect to receive a body of either Foo= or Bar=. This schema causes the following Swagger UI interface to be rendered:

This is not correct. It is representing the form as a JSON payload and causes invalid requests to be sent to the endpoint in which the Swagger UI is encoding each character as a separate form value. E.g. sending a value of hi would result in the body 0=h&1=i.

This same issue occurs when using anyOf.

When using allOf, however, a correct representation is rendered as below:

Are there any updates here regarding the support for such oneOf and anyOf usage? Alternatively; am I incorrectly defining my schema in some way to achieve such usage?

Is there any clear date on when this will be implemented?

+1 this is something I would need in the UI

After due consideration, I could not arrive at an acceptable UI. Of course, if the one assumes the api specification is: 1) simple 2) has relatively few such named attributes, and 3) doesn’t nest oneOf’s and/or anyOf’s I did manage to come up with “on the back of the napkin” UX design that I think would be acceptable. It fell into the scenario @mgranciano describes or my simple oneOf schema. However my draft UX falls apart when oneOf itself includes an attribute containing another oneOf or anyOf (or visa-versa).

Just as a comment: I wonder if we could approach the solution differently. Perhaps the Example Value | Model can highlight that oneOf and/or anyOf applies by outputting a different styles color or background-color. Being alerted, the user can work through the implications. Just offering that as an idea.

@shockey I want to fix this issue. But I don’t know how to do. There are two cases: 1.

schema: 
  type: array 
  items:  
    oneOf:  
      - type: string  
      - type: integer

I can do like this

schema:
  oneOf:
  - $ref: '#/components/schemas/a'
  - $ref: '#/components/schemas/b'

components:
  schemas:
    a:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    b:
      type: array
      items:
        type: integer
        format: int64

I can do like this

Or something more complicated like in model tab? What do you think?

I am facing the same issue. Using oneOf in requestBody is fine. You can not see the exact example but can still see the model. User can dig inside.

However, responses not working. 😃 Just to share

Hey @crussell52, I tagged it as a feature because Swagger-UI hasn’t/doesn’t support oneOf responses, as opposed to there being an issue with how a oneOf responses implementation renders things.

In other news… Work on this stalled (clearly), I’m going to do my best to circle back in January.

Can’t wait to see this 🤗🤗

Everyone - asking whether it’s already implemented or adding +1 comments is not helpful. If we haven’t updated that it’s implemented, then it’s not been implemented, no need to ask. +1’ing just adds more notifications - you can use the reaction feature on the top comment to +1 and show us that this is important to you.

Nobody saying this is not important - however, there are real issues implementing support for it and until we resolve those there’s nothing to implement. If you have any thoughts on how to address the concerns (and they are all written above), feel free to join the conversation. However, don’t expect us to make a solution that works for you if it’s “good enough”, but doesn’t address the issues as a whole. We’re not going to replace one issue with a set of others.

For clarification: I was referring to Swagger-UI displaying the onOf alternate schemas in the Responses area as either an Example Value or Model or both.

Here is what Swagger-UI 3.11.0 displays and its associated OpenAPI 3.0 specification fragment. You’ll see nothing displayed.

Again, this is not a hot issue for me – just something that I wanted to go on record. Perhaps I added the comment into the wrong issue.

@jaredbarranco ’ solution worked for me.

I’d like to thank alecnmk for the help with the code.

Yes, there are 67 open pull requests. At least 10 are ready to merge.

Still waiting on ability to show example value.

@ppazos - https://app.swaggerhub.com/help/openapi-3-support look under the header Convert OpenAPI 2.0 APIs to OpenAPI 3.0.

+1

of those I prefer the second one. Since we can name examples in the yaml, would it be a stretch to have example1: text box

example2: text box