@fastify/swagger-ui

The uiConfig option allows you to pass configuration directly to the underlying Swagger UI library. Note that functions provided in uiConfig are executed in the browser and cannot access backend code. You can access the Swagger UI instance via the ui variable (assigned to window.ui).

Multiple Specifications

To enable a dropdown for switching between multiple API definitions, use the urls option within uiConfig. Each URL must be reachable by the client.

await fastify.register(require('@fastify/swagger-ui'), {
  uiConfig: {
    urls: [
      { url: '/documentation/json', name: 'Main API' },
      { url: '/documentation/openapi.yaml', name: 'Other API' }
    ],
    'urls.primaryName': 'Other API'
  }
})

const fastify = require('fastify')()

await fastify.register(require('@fastify/swagger'))

await fastify.register(require('@fastify/swagger-ui'), {
  uiConfig: {
    onComplete: function () {
      alert('ui has type of ' + typeof ui) // 'ui has type of object'
      alert('fastify has type of ' + typeof fastify) // 'fastify has type of undefined'
      alert('window has type of ' + typeof window) // 'window has type of object'
      alert('global has type of ' + typeof global) // 'global has type of undefined'
    }
  }
})

To use @fastify/swagger-ui, you must first register @fastify/swagger in your project. Then, register @fastify/swagger-ui with your desired configuration options.

Key configuration options include:

• routePrefix: The URL path where the Swagger UI will be served.
• uiConfig: Configuration for the Swagger UI interface (e.g., docExpansion, deepLinking).
• uiHooks: Lifecycle hooks for the UI requests (onRequest, preHandler).
• staticCSP: Boolean to enable static Content Security Policy.
• transformStaticCSP: Function to transform the CSP header.
• transformSpecification: Function to transform the Swagger/OpenAPI specification object.
• transformSpecificationClone: Boolean to determine if the specification should be cloned before transformation.

Security Note: When defining security in your route schemas, the key (e.g., apiKey) must match the name of the security scheme declared in components.securitySchemes (OpenAPI 3) or securityDefinitions (Swagger 2.0). The empty array [] represents scopes and is used for API key authentication.

import fastify from 'fastify'

const app = fastify()

// 1. Register @fastify/swagger first
await app.register(import('@fastify/swagger'))

// 2. Register @fastify/swagger-ui
await app.register(import('@fastify/swagger-ui'), {
  routePrefix: '/documentation',
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header,
  transformSpecification: (swaggerObject, request, reply) => { return swaggerObject },
  transformSpecificationClone: true
})

// 3. Define routes with schemas
app.put('/some-route/:id', {
  schema: {
    description: 'post some data',
    tags: ['user', 'code'],
    summary: 'qwerty',
    params: {
      type: 'object',
      properties: {
        id: {
          type: 'string',
          description: 'user id'
        }
      }
    },
    body: {
      type: 'object',
      properties: {
        hello: { type: 'string' },
        obj: {
          type: 'object',
          properties: {
            some: { type: 'string' }
          }
        }
      }
    },
    response: {
      201: {
        description: 'Successful response',
        type: 'object',
        properties: {
          hello: { type: 'string' }
        }
      },
      default: {
        description: 'Default response',
        type: 'object',
        properties: {
          foo: { type: 'string' }
        }
      }
    },
    security: [
      {
        "apiKey": []
      }
    ]
  }
}, (req, reply) => {})

await app.ready()

Use transformSpecification to modify the swagger document dynamically on every request (e.g., to change the host based on the request hostname).

By default, the swaggerObject passed to this function is a deep clone (controlled by transformSpecificationClone: true). If you want to implement your own cloning or caching logic for performance, set transformSpecificationClone: false.

const fastify = require('fastify')()
const LRU = require('tiny-lru').lru
const rfdc = require('rfdc')()

await fastify.register(require('@fastify/swagger'))

const swaggerLru = new LRU(1000)
await fastify.register(require('@fastify/swagger-ui'), {
  transformSpecificationClone: false,
  transformSpecification: (swaggerObject, req, reply) => {
    if (swaggerLru.has(req.hostname)) {
      return swaggerLru.get(req.hostname)
    }
    const clonedSwaggerObject = rfdc(swaggerObject)
    clonedSwaggerObject.host = req.hostname
    swaggerLru.set(req.hostname, clonedSwaggerObject)
    return clonedSwaggerObject
  }
})

When registering the @fastify/swagger-ui plugin, you can provide several configuration options to customize the documentation interface, routing, and behavior.

| Option             | Default         | Description                                                                                                                                                                                                                                       |
 | ------------------ | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | baseDir              | undefined       | Directory from which the Swagger UI static assets (served under `<routePrefix>/static/`) are loaded, instead of the `static` folder shipped with this plugin. Any other file in that directory is also served relative to `routePrefix`, e.g. spec files referenced via `$ref`. When not set, only the bundled Swagger UI assets are served. Provided value should be an absolute path without trailing slash. See [Bundling](#bundling). |
 | initOAuth            | {}              | Configuration options for [Swagger UI initOAuth](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).                                                                                                                                                            |
 | routePrefix          | '/documentation' | Overwrite the default Swagger UI route prefix.                                                                                                                                                                     |
 | indexPrefix          | ''              | External path prefix added to the asset links in the index page, for when the Fastify server is behind path based routing (e.g. NGINX). See [Running behind a reverse proxy](#running-behind-a-reverse-proxy).                                                                    |
 | 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.                                                                                                                                          |
 | transformSpecification     | undefined       | Synchronous function to transform the swagger document.                                                                                                                                                            |
 | transformSpecificationClone| true            | Provide a deepcloned swaggerObject to transformSpecification                                                                                                                                                                                      |
 | uiConfig             | {}              | Configuration options for [Swagger UI](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md).                                                                                                                        |
 | uiHooks              | {}              | Additional hooks for the documentation's routes. You can provide the `onRequest` and `preHandler` hooks with the same [route's options](https://fastify.dev/docs/latest/Reference/Routes/#routes-options) interface.                                                               |
 | theme                | {}              | Add custom JavaScript and CSS to the Swagger UI web page                                                                                                                                                                       |
 | logLevel             | info            | Allow to define route log level.                                                                                                                                                                                                    |