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: ...
Solved! Go to 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
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!
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.
"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
Subject | Author | Latest Post |
---|---|---|