Multiple success and failure sections for a single code

[alifemove]

Is your feature request related to a problem? Please describe.
Endpoints that return the same error or success code for multiple reasons; i.e. 200 that returns a specific payload structure if there is only 1 record vs a different payload structure if there are > 1 records

Describe the solution you'd like
Be able to do something along the lines of

@success 200 {object} SuccessSingle
@success 200 {object} SuccessPage
@failure     400 "Bad Request"
@failure     400 "Invalid filter in query"

I found that I could use <br/> in the failures to basically do the same thing, but not sure about success.

@failure    400 "Bad Request<br/>Invalid filter in query"

[alexrjones]

Both OpenAPI 2.0 and 3+ specs only support one response type per status code (ref). In 3+ I think you could use oneOf to describe this, which would be relatively easy to implement. In 2.0 you'd need to use a combination of allOf and discriminator, which is more complicated, because discriminator comes with some restrictions:

The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the required property list. When used, the value MUST be the name of this schema or any schema that inherits it.