Add support for different response content types

[gyszalai]

Swagger supports different content types in the response like this:

/health:
  get:
    responses:
      '200':
        description: Successful response
        content:
          text/plain:
            schema:
              type: string
              enum: ['UP','DOWN']

Currently it is not possible to define a response like this with fastify-swagger.

[mcollina]

Currently we don’t. I think we should enable this, but I’m not exactly seeing how. Would you mind to do a proposal? A PR would even be better. We might even be lacking support for this in fastify itself. Il giorno mer 17 ott 2018 alle 10:22 Gyula Szalai <notifications@github.com> ha scritto:

…

Swagger supports different content types in the response like this: /health: get: responses: '200': description: Successful response content: text/plain: schema: type: string enum: ['UP','DOWN'] Currently it is not possible to define a response like this with fastify-swagger. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#117>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADL41g_ezDOCGdyy3eVon1ICna3R4Jkks5ulujYgaJpZM4XjYWt> .

[climba03003]

OpenAPIv2 (aka Swagger) do not support this format. but OpenAPIv3 does.
As we added the support for OpenAPIv3. You can follow the document do achieve it.
Resolved by #333

[olafkrueger]

@climba03003
First, many thanks for working on the OAS3 stuff!!
Maybe I overlook it, but is there any example of how we could add different content/media types to a particular response?
I've no idea how we could format a valid json response schema without adding a content object which holds the different media types.

Something like this (I just translated the OAS3 YAML example to JSON):

{
  "responses": {
    "200": {
      "description": "OK",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "fullTime": {
                "type": "boolean"
              }
            }
          }
        },
        "application/xml": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "name": {
                "type": "string"
              },
              "fullTime": {
                "type": "boolean"
              }
            }
          }
        }
      }
    }
  }
}

Not totally sure, but after looking at the fastify-swagger code it seems to me that the openapi implementation still relies on consumes which has been removed since OAS3?:

fastify-swagger/lib/spec/openapi/utils.js

Line 148 in 36bf409

function resolveBodyParams (content, schema, consumes, ref) {

For the sake of completeness, just an example of the origin OAS3 docs which is about different media types:

paths:
  /employees:
    get:
      summary: Returns a list of employees.
      responses:
        '200':      # Response
          description: OK
          content:  # Response body
            application/json:   # One of media types
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean
            application/xml:    # Another media types
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  fullTime: 
                    type: boolean

Thanks!
Olaf

[climba03003]

This packages is not independent from fastify itself. fastify cannot specify different response schema according to the media types with the same status code. So, for dynamic mode, we cannot do it either.

If you need to do it. Please use static mode.

For the question about comsumes, the answers is yes. OpenAPIv3 still rely on it for the dynamic generation.

[olafkrueger]

fastify cannot specify different response schema according to the media types with the same status code

Thank you for this clear answer and sorry for beeing not so clear... I hope I didn't waste too much of your time ;-)
However, I really wonder how it could make sense to resolve this by using static mode if fastify itself is not able to handle it?

If it makes sense, one last question:
Is it possible to use the static mode for just a particular route and keep the dynamic mode for all other routes?

Beside all that it looks like that it's easier and more pragmatic to split the different media types across different routes, something like this:

GET /my/resource/:id/pdf
GET /my/resource/:id/json

[olafkrueger]

However, I really wonder how it could make sense to resolve this by using static mode if fastify itself is not able to handle it?

Forget about this question, it makes sense ;-)

[climba03003]

However, I really wonder how it could make sense to resolve this by using static mode if fastify itself is not able to handle it?

You can achieve it by not passing schema.response to disable the serialization of response.
Then you can reply with reply.type(...).send(...) according to your request.
In that case, you can use static mode to write document and show what different response will be given.

Is it possible to use the static mode for just a particular route and keep the dynamic mode for all other routes?

No, we current do not allow to pass path from dynamic mode. Maybe a PR or Issue should raised if you need this.
I do not know if exterenalDocs works in this case because I never use this field.

If you have any more question. Please open a new Issue.

[olafkrueger]

Got it, thank you for your detailed explanation!

[giovanni-bertoncelli]

So right now there is no way to change a response type in the swagger documentation generated?

[climba03003]

So right now there is no way to change a response type in the swagger documentation generated?

You can specify the response type, but you cannot have different type with different response schema.
e.g. text/html return string and application/octet-stream return buffer.

If you have further question, please raise an issue.

[matthiasg]

Where can the response type be configured so it appears in swagger ?

[climba03003]

Where can the response type be configured so it appears in swagger ?

produces for response.