MIGRATION.md

Migration

Migrating from version 7 to 8

As of version 8 @fastify/swagger is only responsible for generating valid swagger/openapi-specifications. The new @fastify/swagger-ui plugin is responsible for serving the swagger-ui frontend.

Options in version 7 of @fastify/swagger related to the configuration of the swagger-ui frontend are now options of @fastify/swagger-ui.

The exposeRoute option is removed.

Following are the @fastify/swagger-ui options:

Option	Default	Description
baseDir	undefined	Only relevant if @fastify/swagger used in static-mode and additional schema-files contain referenced schemas. Specify the directory where all spec files that are included in the main one using $ref will be located. By default, this is the directory where the main spec file is located. Provided value should be an absolute path without trailing slash.
initOAuth	{}	Configuration options for Swagger UI initOAuth.
routePrefix	'/documentation'	Overwrite the default Swagger UI route prefix.
staticCSP	false	Enable CSP header for static resources.
transformStaticCSP	undefined	Synchronous function to transform CSP header for static resources if the header has been previously set.
uiConfig	{}	Configuration options for Swagger UI. Must be literal values, see #5710.
uiHooks	{}	Additional hooks for the documentation's routes. You can provide the onRequest and preHandler hooks with the same route's options interface.

The baseDir option is new and is only needed if external spec files should be exposed. baseDir option of @fastify/swagger-ui should be set to the same value as the specification.baseDir option of @fastify/swagger.

Example (static-mode):

before:

import Fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'

const fastify = new Fastify()

await fastify.register(fastifySwagger, {
  mode: 'static',
  specification: {
    path: './examples/example-static-specification.yaml',
    postProcessor: function(swaggerObject) {
      return swaggerObject
    },
    baseDir: '/path/to/external/spec/files/location',
  },
  exposeRoute: true,
  routePrefix: '/documentation',
  initOAuth: { },
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header
})

after:

import Fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'
import fastifySwaggerUi from '@fastify/swagger-ui'

const fastify = new Fastify()

await fastify.register(fastifySwagger, {
  mode: 'static',
  specification: {
    path: './examples/example-static-specification.yaml',
    postProcessor: function(swaggerObject) {
      return swaggerObject
    },
    baseDir: '/path/to/external/spec/files/location'
  }
})

await fastify.register(fastifySwaggerUi, {
  baseDir: '/path/to/external/spec/files/location',
  routePrefix: '/documentation',
  initOAuth: { },
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header
})

Example (dynamic-mode):

before:

import Fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'

const fastify = new Fastify()

await fastify.register(fastifySwagger, {
  mode: 'dynamic',
  openapi: {
    info: {
      title: String,
      description: String,
      version: String,
    },
    externalDocs: Object,
    servers: [ Object ],
    components: Object,
    security: [ Object ],
    tags: [ Object ]
  },
  exposeRoute: true,
  routePrefix: '/documentation',
  initOAuth: { },
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header
})

after:

import Fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'
import fastifySwaggerUi from '@fastify/swagger-ui'

const fastify = new Fastify()

await fastify.register(fastifySwagger, {
  mode: 'dynamic',
  openapi: {
    info: {
      title: String,
      description: String,
      version: String,
    },
    externalDocs: Object,
    servers: [ Object ],
    components: Object,
    security: [ Object ],
    tags: [ Object ]
  }
})

await fastify.register(fastifySwaggerUi, {
  routePrefix: '/documentation',
  initOAuth: { },
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header
})