Problems adding two examples for a response

[ppazos]

Hi, I have an endpoint that can return a response based on two different schemas, which I have on the response with oneOf.

I'm trying to add examples of those two payloads to the response of that endpoint, but when I add the second example, I get an error in the YAML.

Couldn't find an example for this and not sure if that is possible. IMO is a pretty common use case.

This is what I'm trying:

responses:
        '200':
          description: lots of good stuff here..
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/A'
                  - $ref: '#/components/schemas/B'
              example: # also tried with "examples"
                first example:
                  value: ...
                anoter example:
                  value: ...

[HKosova]

To specify multiple examples you need to use "examples" not "example"; the rest of your YAML is correct.

"examples" are currently not displayed in the API docs, but this is planned for the future. You can get a sneak peek at the upcoming design here:

https://github.com/swagger-api/swagger-ui/issues/2651#issuecomment-493245789

Stay tuned!

[ppazos]

In fact with "example" and specifying a list, the yaml validates.

example:
  - ex1
     ....
  - ex2
      .....

With "examples" that doesn't validate. In the first item of th list I get "should be an object".

Can you share a valid code with more than one example for the response?

Thanks.

[HKosova · Accepted solution]

"example" (singular) expects a single inline example, so this definition

example:
  - ex1
     ....
  - ex2
      .....

means that the example value is literally

  - ex1
     ....
  - ex2
      .....

The syntax with multiple "examples" would look like this:

      responses:
        '200':
          description: OK
          content:
            application/json: 
              schema:
                oneOf:
                  - $ref: '#/components/schemas/A'
                  - $ref: '#/components/schemas/B'
              examples:
                cat:
                  summary: An example of a cat
                  value:
                    name: Fluffy
                    petType: Cat
                    color: White
                    gender: male
                    breed: Persian
                dog:
                  summary: An example of a dog with a cat's name
                  value:
                    name: Puma
                    petType: Dog
                    color: Black
                    gender: female
                    breed: Mixed