@lineupr/fastify-swagger-ui

Forked from @fastify/swagger-ui and added Swagger UI 5.0.0 alpha which supports OpenAPI 3.1.

---

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!

1const fastify = require('fastify')()
2
3await fastify.register(require('@fastify/swagger'))
4
5await fastify.register(require('@fastify/swagger-ui'), {
6  routePrefix: '/documentation',
7  uiConfig: {
8    docExpansion: 'full',
9    deepLinking: false
10  },
11  uiHooks: {
12    onRequest: function (request, reply, next) { next() },
13    preHandler: function (request, reply, next) { next() }
14  },
15  staticCSP: true,
16  transformStaticCSP: (header) => header,
17  transformSpecification: (swaggerObject, request, reply) => { return swaggerObject },
18  transformSpecificationClone: true
19})
20
21fastify.put('/some-route/:id', {
22  schema: {
23    description: 'post some data',
24    tags: ['user', 'code'],
25    summary: 'qwerty',
26    params: {
27      type: 'object',
28      properties: {
29        id: {
30          type: 'string',
31          description: 'user id'
32        }
33      }
34    },
35    body: {
36      type: 'object',
37      properties: {
38        hello: { type: 'string' },
39        obj: {
40          type: 'object',
41          properties: {
42            some: { type: 'string' }
43          }
44        }
45      }
46    },
47    response: {
48      201: {
49        description: 'Successful response',
50        type: 'object',
51        properties: {
52          hello: { type: 'string' }
53        }
54      },
55      default: {
56        description: 'Default response',
57        type: 'object',
58        properties: {
59          foo: { type: 'string' }
60        }
61      }
62    },
63    security: [
64      {
65        "apiKey": []
66      }
67    ]
68  }
69}, (req, reply) => {})
70
71await 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.
uiHooks	{}	Additional hooks for the documentation's routes. You can provide the onRequest and preHandler hooks with the same route's options interface.
theme	{}	Add custom JavaScript and CSS to the Swagger UI web page
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

uiConfig

To configure Swagger UI, you need to modify the uiConfig option. It's important to ensure that functions are self-contained. Keep in mind that you cannot modify the backend code within the uiConfig functions, as these functions are processed only by the browser. You can reference the Swagger UI element using ui, which is assigned to window.ui.

Example

1const fastify = require('fastify')()
2
3await fastify.register(require('@fastify/swagger'))
4
5await fastify.register(require('@fastify/swagger-ui'), {
6  uiConfig: {
7    onComplete: function () {
8      alert('ui has type of ' + typeof ui) // 'ui has type of object'
9      alert('fastify has type of ' + typeof fastify) // 'fastify has type of undefined'
10      alert('window has type of ' + typeof window) // 'window has type of object'
11      alert('global has type of ' + typeof global) // 'global has type of undefined'
12    }
13  }
14})

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

1const fastify = require('fastify')()
2
3await fastify.register(require('@fastify/swagger'))
4
5await fastify.register(require('@fastify/swagger-ui'), {
6  transformSpecification: (swaggerObject, req, reply) => {
7    swaggerObject.host = req.hostname
8    return swaggerObject
9  }
10})

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

1const fastify = require('fastify')()
2const LRU = require('tiny-lru').lru
3const rfdc = require('rfdc')()
4
5await fastify.register(require('@fastify/swagger'))
6
7const swaggerLru = new LRU(1000)
8await fastify.register(require('@fastify/swagger-ui'), {
9  transformSpecificationClone: false,
10  transformSpecification: (swaggerObject, req, reply) => {
11    if (swaggerLru.has(req.hostname)) {
12      return swaggerLru.get(req.hostname)
13    }
14    const clonedSwaggerObject = rfdc(swaggerObject)
15    clonedSwaggerObject.host = req.hostname
16    swaggerLru.set(req.hostname, clonedSwaggerObject)
17    return clonedSwaggerObject
18  }
19})

theme

You can add custom JavaScript and CSS to the Swagger UI web page by using the theme option.

Example

1const fastify = require('fastify')()
2
3fastify.register(require('@fastify/swagger'))
4
5await fastify.register(require('@fastify/swagger-ui'), {
6  theme: {
7    title: 'My custom title',
8    js: [
9      { filename: 'special.js', content: 'alert("client javascript")' }
10    ],
11    css: [
12      { filename: 'theme.css', content: '* { border: 1px red solid; }' }
13    ],
14    favicon: [
15      {
16        filename: 'favicon.png',
17        rel: 'icon',
18        sizes: '16x16',
19        type: 'image/png',
20        content: Buffer.from('iVBOR...', 'base64')
21      }
22    ]
23  }
24})

You can add custom JavaScript and CSS to the Swagger UI web page by using the theme option.

logo

It's possible to override the logo displayed in the top bar by specifying:

await fastify.register(require('@fastify/swagger-ui'), {
  logo: {
    type: 'image/png',
    content: Buffer.from('iVBOR...', 'base64')
  },
  theme: {
    favicon: [
      {
        filename: 'favicon.png',
        rel: 'icon',
        sizes: '16x16',
        type: 'image/png',
        content: Buffer.from('iVBOR...', 'base64')
      }
    ]
  }
})

Protect your documentation routes

You can protect your documentation by configuring an authentication hook. Here is an example using the @fastify/basic-auth plugin:

Example

1const fastify = require('fastify')()
2const crypto = require('crypto')
3
4fastify.register(require('@fastify/swagger'))
5
6// perform constant-time comparison to prevent timing attacks
7function compare (a, b) {
8  a = Buffer.from(a)
9  b = Buffer.from(b)
10  if (a.length !== b.length) {
11    // Delay return with cryptographically secure timing check.
12    crypto.timingSafeEqual(a, a)
13    return false
14  }
15
16  return crypto.timingSafeEqual(a, b)
17}
18
19await fastify.register(require('@fastify/basic-auth'), {
20  validate (username, password, req, reply, done) {
21    let result = true
22    result = compare(username, validUsername) && result
23    result = compare(password, validPassword) && result
24    if (result) {
25      done()
26    } else {
27      done(new Error('Access denied'))
28    }
29  },
30  authenticate: true
31})
32
33await fastify.register(require('@fastify/swagger-ui', {
34  uiHooks: {
35    onRequest: fastify.basicAuth
36  }
37})

License

Licensed under MIT.