Allow for multiple response schemas for each response code

Example

  responses:
    200:
      description: An array of events
      schema:
        type: array
        items:
          $ref: '#/definitions/Event'
    200:
      description: |
        An array of flattened events. This is the response
        object when singleEvents is True.
      schema:
        type: array
        items:
          $ref: '#/definitions/EventFlat'
    default:
      description: Unexpected error
      schema:
        $ref: '#/definitions/Error'

[webron]

I doubt we’ll support that any time soon. One of the leading principles we have behind Swagger is API determinism. By saying that a single response may return various object types, that pretty much breaks that principle.

[mclate]

Also would vote for adding multiple responses with the same code. The best example would be any 400 (Bad request) error which can be caused by many reasons. Take in example validation errors: missing fields, extra fields passed or simply wrong data provided - these all are different errors grouped under the same status code where exact error is returned in response playload, which may vary for each situation. This is still considered as deterministic behaviour as it is uniquely defined in response playload.