Multiple Request Examples in Swagger 2.0 Yaml

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