Package Exports

@fastify/swagger-ui
@fastify/swagger-ui/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@fastify/swagger-ui) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@fastify/swagger-ui

A Fastify plugin for serving Swagger UI.

Supports Fastify versions 4.x.

Install

npm i @fastify/swagger-ui

Usage

Add it with @fastify/swagger to your project with register, pass it some options, call the swagger API, and you are done!

const fastify = require('fastify')()

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

await fastify.register(require('@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
})

fastify.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 fastify.ready()

API

Register options

Options

Option	Default	Description
baseDir	undefined	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.
transformSpecification	undefined	Synchronous function to transform the swagger document.
transformSpecificationClone	true	Provide a deepcloned swaggerObject to transformSpecification
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.
logLevel	info	Allow to define route log level.

The plugin will expose the documentation with the following APIs:

URL	Description
`'/documentation/json'`	The JSON object representing the API
`'/documentation/yaml'`	The YAML object representing the API
`'/documentation/'`	The swagger UI
`'/documentation/*'`	External files that you may use in `$ref`

transformSpecification

There can be use cases, where you want to modify the swagger definition on request. E.g. you want to modify the server definition based on the hostname of the request object. In such a case you can utilize the transformSpecification-option.

Example

const fastify = require('fastify')()

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

await fastify.register(require('@fastify/swagger-ui'), {
  transformSpecification: (swaggerObject, req, reply) => {
    swaggerObject.host = req.hostname
    return swaggerObject
  }
})

By default fastify.swagger() will be deepcloned and passed to the transformSpecification-function, as fastify.swagger() returns a mutatable Object. You can disable the deepcloning by setting transformSpecificationClone to false. This is useful, if you want to handle the deepcloning in the transformSpecification function.

Example with caching

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
  }
})

License

Licensed under MIT.