Add 'produces' at response level

[dolmen]

In Swagger 2.0 produces is defined at the operation level and applies to all responses. This forbid to uses different MIME types for different responses and to use for example a specific MIME type for errors, as proposed in RFC 7807 ("Problem Details for HTTP APIs", published in March 2016).

[ePaul]

While this is true, the proposed solution would go too short – we also need to allow responses with the same response code, but differing in produces MIME type (and result schema). (This relates to #146.)

[DavidBiesack]

👍 to what @ePaul wrote - our 200 responses return different representations based on Accept headers; others want different representations based on other (query) parameters, etc.

[webron]

How is this different than #146?

[ePaul]

@webron As I understand the original request, this just wants to add a produces field to each response, e.g. for explaining that a 4xx response returns application/problem+json while 200 is returning application/my-object+json. (This currently can only be expressed in a description.)

#146 (and my comment) needs e.g. to allow having several 200 responses which differ by its produces property.

[dolmen]

Here is my use case to clarify my request. I'm implementing streaming operation using Server-Sent-Events (see #396).

• The response with status 200 will produce text/event-stream.
• Others responses are errors and are sent as application/json.

The spec should include enough information to be used to build a client that will send Accept: text/event-stream, application/json but expect only Content-Type: text/event-stream for status 200 and only Content-Type: application/json for other status.

Here is how that would be specified in the Operation object:

produces:
- text/event-stream
- application/json
responses:
  '200':
    description: Stream is starting
    produces: ["text/event-stream"]
  default:
    # has produces: ["application/json"]
    $ref: '#/responses/DefaultError'

The Accept header sent by the client would be built by selecting at least one MIME type from the produces of each possible response.

The existing spec is only meant to allow the client to choose the MIME type for all responses of an operation just to select the serialisation format between application/xml or application/json. This does not fit my use case.

[fehguy]

@dolmen please look at the solution that was accepted by the TDC:

#761

[dolmen]

In fact, there is already a way to declare produces at responses level by adding a header constraint for Content-Type:

responses:
  '200':
    description: Stream is starting
    headers:
      'Content-Type':
        type: string
        enum: ["text/event-stream"]

(but unfortunately swagger-ui doesn't (yet) shows the enum)

[webron]

With the new Response Object's content you can specify specific. consumes and produces have been removed entirely.