Build-Docs OneOf Example

[thecork3004]

I hope I explain my issue, because I must admit I don't know much about openapi and am simply trying to convert some files provided by my dev team to HTML to share with customers so please bare with me if i use incorrect terminology throughout.

The issue I'm having is that one of my endpoints is utilising oneOf in its schema.

When we look at the endpoint in swaggerhub, the "Example" that is presented, is of the first in the list of "oneOfs" which is what we would expect. When I convert this to html using redocly, I see two buttons next to "one of" called "In Request" which when selected dynamically presents the correct schema below, but the example on the right hand side does not change, and counterintuitively shows the 2nd of the two oneOf options, the opposite of what swaggerhub does. I find this counter intuitive because when the page is loaded, the "first" option is always selected, and yet the example is of the 2nd (in my case) of the options.

My questions are the following:

1. Is this expected behaviour or an issue?
2. Can the example be set to change when the buttons are selected just like the schema does
3. Can the buttons be labelled rather than just both be called "In Request"

Thanks, i really appreciate if anyone can give me guidance and again apologies if this is not explained properly from my unknowledgeable perspective.

[tatomyr]

Hi @thecork3004, this is a Redoc issue. Will transfer it to the correct repo.

[thecork3004]

Any help here?

[RomanPidkostelnyi]

Hi @thecork3004,

1. For me, the example shows the first option. Maybe it is related to your definition.

   2.Currently, we don't synchronize examples with the selected 'oneOf' options.

2. Yes, it can. You need to change it in your OpenAPI definition. Here are some examples. In the first case, if you will have a definition with just a list of available options and their types, then the type will be used for label.
   defintion:

ticketType:
     oneOf:
       -  type: string
           enum: ['general']
       -  type: string
           enum: ['adult', 'child', 'senior']

In the second scenario, you will utilize certain components, and then the name of a component will be used as a label. definition

paymentMethod:
       oneOf:
          - $ref: '#/components/schemas/Cash'
          - $ref: '#/components/schemas/CreditCard'

components:
    schemas:
        Cash:
          type: object
          properties:
            currency:
              type: string
              enum: [Euro, USD]
        CreditCard:
          type: object
          properties:
            bank:
              type: string
              enum: [MasterCard, Visa]

If you have any more questions, please ping me. I hope I can help you.

[jeremyfiel]

3. Can the buttons be labelled rather than just both be called "In Request"

You can also achieve the button naming by using the title attribute in the schema. If they are missing, they can be easily added and won't affect your schema validation.

openapi: 3.0.3
info:
  title: '2563'
  version: '0.0.1'
servers:
  - url: https://redocly.com
paths:
  '/thing':
    get:
      summary: testing labels using title attribute
      responses:
        '200':
          description: OK
          content:
            'application/json':
              schema:
                oneOf:
                  - title: this
                    type: object
                    additionalProperties: false
                    properties:
                      this:
                        type: string
                  - title: that
                    type: object
                    additionalProperties: false
                    properties:
                      that:
                        type: string
              examples:
                this:
                  value:
                    this: 'test'
                that:
                  value:
                    that: 'test'

---