Multiple Request Examples in Swagger 2.0 Yaml - swagger

Question

I have an API which has some mutually exclusive arguments for json payloads. I would like to display this in multiple examples but the schema in the yaml file seems to only be able to generate one example.
If my inputs could be:
{
"text": "some text"
}
OR
{
"list": ["some text", "some more"]
}
BUT NOT
{
"text": "some text",
"list": ["some text", "some more"]
}
how can this be done in swagger 2.0?
A schema definition like the following is misleading
definitions:
MutexSchema:
type: object
properties:
list:
type: array
items:
type: string
example: ["some text", "some more"]
text:
type: string
example: "Some text"
And it seems you cannot specify multiple body options. What would be a good way to show the mutually exclusive payloads with their corresponding responses?

Answer 1

OpenAPI 2.0 does not support mutually exclusive properties, but you can emulate this by adding minProperties: 1 and maxProperties: 1 to your schema. This essentially means that only text or only list can be passed, but not both.
definitions:
MutexSchema:
type: object
properties:
list:
type: array
items:
type: string
example: ["some text", "some more"]
text:
type: string
example: "Some text"
minProperties: 1 # <--------
maxProperties: 1
What would be a good way to show the mutually exclusive payloads with their corresponding responses?
Migrate to OpenAPI 3 which supports oneOf and multiple examples for requests and responses. Note that there's no way to correlate request and response examples, but you can provide additional information in the description fields.
paths:
/something:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MutexSchema'
# Request body examples
examples:
text example:
summary: Example with text
value:
text: Some text
list example:
summary: Example with list
value:
list: [some text, some more]
responses:
'200':
description: OK
content:
application/json:
schema:
...
# Response examples
examples:
ex1:
summary: ...
value:
...
ex2:
summary: ...
value:
...
components:
schemas:
MutexSchema:
oneOf:
- $ref: '#/components/schemas/Text'
- $ref: '#/components/schemas/List'
Text:
type: object
required:
- text # <--- Property must be marked as required for oneOf to work
properties:
text:
type: string
example: Some text
additionalProperties: false
List:
type: object
required:
- list # <--- Property must be marked as required for oneOf to work
properties:
list:
type: array
items:
type: string
example: [some text, some more]
additionalProperties: false