cancel
Showing results for 
Search instead for 
Did you mean: 
Welcome to the September Hub-bub

We are inviting you to join our exciting online event where you can learn a lot of useful information, share your knowledge and have fun. Each week, we will reward the best posters with free gift cards .

Just pick any topic you like in the SwaggerHub Community, or create your own to dive into the wonderful September Hub-bub.

Event duration: September 2-27. More information.

This Week Top Contributors:

We will decide the winners next Monday

Problems adding two examples for a response

SOLVED
New Contributor

Problems adding two examples for a response

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: ...
1 ACCEPTED SOLUTION

Accepted Solutions
Moderator

Re: Problems adding two examples for a response

"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

 


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.

Join the September Hub-bub to show off, learn and win
3 REPLIES 3
Moderator

Re: Problems adding two examples for a response

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!


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.

Join the September Hub-bub to show off, learn and win
New Contributor

Re: Problems adding two examples for a response

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.

 

 

 

Moderator

Re: Problems adding two examples for a response

"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

 


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.

Join the September Hub-bub to show off, learn and win
New Here?
Join us and watch the welcome video:
Top Kudoed Authors
Join the September Hub-bub to show off, learn and win