@fastify/swagger

A Fastify plugin for serving Swagger (OpenAPI v2) or OpenAPI v3 schemas, which are automatically generated from your route schemas, or an existing Swagger/OpenAPI schema.

If you are looking for a plugin to generate routes from an existing OpenAPI schema, check out fastify-openapi-glue.

The following plugins serve Swagger/OpenAPI front-ends based on the swagger definitions generated by this plugin:

• @fastify/swagger-ui
• @scalar/fastify-api-reference

See the migration guide for migrating from @fastify/swagger version <=7.x to version >=8.x.

Install

npm i @fastify/swagger

Compatibility

Plugin version	Fastify version
>=9.x	^5.x
>=7.x <9.x	^4.x
^6.x	^3.x
>=3.x <6.x	^2.x
>=1.x <3.x	^1.x

Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin in the table above. See Fastify's LTS policy for more details.

Usage

Add it with register, pass it options, call the swagger API, and you are done! Below is an example of configuring the OpenAPI v3 specification with Fastify Swagger:

1const fastify = require('fastify')()
2
3await fastify.register(require('@fastify/swagger'), {
4  openapi: {
5    openapi: '3.0.0',
6    info: {
7      title: 'Test swagger',
8      description: 'Testing the Fastify swagger API',
9      version: '0.1.0'
10    },
11    servers: [
12      {
13        url: 'http://localhost:3000',
14        description: 'Development server'
15      }
16    ],
17    tags: [
18      { name: 'user', description: 'User related end-points' },
19      { name: 'code', description: 'Code related end-points' }
20    ],
21    components: {
22      securitySchemes: {
23        apiKey: {
24          type: 'apiKey',
25          name: 'apiKey',
26          in: 'header'
27        }
28      }
29    },
30    externalDocs: {
31      url: 'https://swagger.io',
32      description: 'Find more info here'
33    }
34  }
35})
36
37fastify.put('/some-route/:id', {
38  schema: {
39    description: 'post some data',
40    tags: ['user', 'code'],
41    summary: 'qwerty',
42    security: [{ apiKey: [] }],
43    params: {
44      type: 'object',
45      properties: {
46        id: {
47          type: 'string',
48          description: 'user id'
49        }
50      }
51    },
52    body: {
53      type: 'object',
54      properties: {
55        hello: { type: 'string' },
56        obj: {
57          type: 'object',
58          properties: {
59            some: { type: 'string' }
60          }
61        }
62      }
63    },
64    response: {
65      201: {
66        description: 'Successful response',
67        type: 'object',
68        properties: {
69          hello: { type: 'string' }
70        }
71      },
72      default: {
73        description: 'Default response',
74        type: 'object',
75        properties: {
76          foo: { type: 'string' }
77        }
78      }
79    }
80  }
81}, (req, reply) => { })
82
83await fastify.ready()
84fastify.swagger()

With @fastify/autoload

Register @fastify/swagger before routes are loaded with @fastify/autoload:

1const fastify = require('fastify')()
2const fastify = fastify()
3await fastify.register(require('@fastify/swagger'))
4fastify.register(require("@fastify/autoload"), {
5  dir: path.join(__dirname, 'routes')
6})
7await fastify.ready()
8fastify.swagger()

API

Register options

Modes

@fastify/swagger supports dynamic and static registration modes:

Dynamic

dynamic is the default mode, which auto-generates API schemas from route schemas:

1// All of the below parameters are optional but are included for demonstration purposes
2{
3  // swagger 2.0 options
4  swagger: {
5    info: {
6      title: String,
7      description: String,
8      version: String
9    },
10    externalDocs: Object,
11    host: String,
12    schemes: [ String ],
13    consumes: [ String ],
14    produces: [ String ],
15    tags: [ Object ],
16    securityDefinitions: Object
17  },
18  // openapi 3.0.3 options
19  // openapi: {
20  //   info: {
21  //     title: String,
22  //     description: String,
23  //     version: String,
24  //   },
25  //   externalDocs: Object,
26  //   servers: [ Object ],
27  //   components: Object,
28  //   security: [ Object ],
29  //   tags: [ Object ]
30  // }
31}

All properties in the Swagger (OpenAPI v2) and OpenAPI v3 specifications can be used. @fastify/swagger generates API schemas adhering to the Swagger specification by default. Providing an openapi option generates OpenAPI compliant API schemas instead.

Examples of using @fastify/swagger in dynamic mode:

• Using the swagger option
• Using the openapi option

Static

static mode must be configured explicitly. It serves an existing Swagger or OpenAPI schema passed to specification.path:

1{
2  mode: 'static',
3  specification: {
4    path: './examples/example-static-specification.yaml',
5    postProcessor: function(swaggerObject) {
6      return swaggerObject
7    },
8    baseDir: '/path/to/external/spec/files/location',
9  },
10}

The specification.postProcessor parameter is optional and allows modifying the Swagger object on the fly, e.g., based on the environment. It accepts swaggerObject - a JavaScript object parsed from a yaml or json file and should return a Swagger schema object.

specification.baseDir allows specifying the directory where all spec files that are included in the main one using $ref will be located. By default, it is the directory of the main spec file. The value should be an absolute path without a trailing slash.

An example of using @fastify/swagger with static mode enabled can be found here.

Options

Option	Default	Description
hiddenTag	X-HIDDEN	Tag to control hiding of routes.
hideUntagged	false	If true remove routes without tags from resulting Swagger/OpenAPI schema file.
openapi	{}	OpenAPI configuration.
stripBasePath	true	Strips base path from routes in docs.
swagger	{}	Swagger configuration.
transform	null	Transform method for the route's schema and url. documentation.
transformObject	null	Transform method for the swagger or openapi object before it is rendered. documentation.
refResolver	{}	Option to manage the $refs of the application's schemas. Read the $ref documentation
exposeHeadRoutes	false	Include HEAD routes in the definitions
decorator	'swagger'	Overrides the Fastify decorator. documentation.

Transform

Pass a synchronous transform function to modify the route's URL and schema. openapiObject and swaggerObject are also available.

Some possible uses of this are:

• Adding the hide flag to the schema based on URL and schema logic
• Altering the route URL to suit the API spec
• Transforming different schemas (e.g., Joi) to standard JSON schemas
• Hiding routes based on version constraints

This option is available in dynamic mode only.

Examples of all the possible uses mentioned:

1const convert = require('joi-to-json')
2
3await fastify.register(require('@fastify/swagger'), {
4  swagger: { ... },
5  transform: ({ schema, url, route, swaggerObject }) => {
6    const {
7      params,
8      body,
9      querystring,
10      headers,
11      response,
12      ...transformedSchema
13    } = schema
14    let transformedUrl = url
15
16    // Transform the schema as you wish with your own custom logic.
17    // In this example convert is from 'joi-to-json' lib and converts a Joi based schema to json schema
18    if (params) transformedSchema.params = convert(params)
19    if (body) transformedSchema.body = convert(body)
20    if (querystring) transformedSchema.querystring = convert(querystring)
21    if (headers) transformedSchema.headers = convert(headers)
22    if (response) transformedSchema.response = convert(response)
23
24    // can add the hide tag if needed
25    if (url.startsWith('/internal')) transformedSchema.hide = true
26
27    // can transform the url
28    if (url.startsWith('/latest_version/endpoint')) transformedUrl = url.replace('latest_version', 'v3')
29
30    // can add the hide tag for routes that do not match the swaggerObject version
31    if (route?.constraints?.version !== swaggerObject.swagger) transformedSchema.hide = true
32
33    return { schema: transformedSchema, url: transformedUrl }
34  }
35})

The transform function can also be attached to a specific endpoint:

1fastify.get("/", {
2  schema: { ... },
3  config: {
4    swaggerTransform: ({ schema, url, route, swaggerObject }) => { ... }
5  }
6})

If both global and local transform functions are available for an endpoint, the endpoint-specific transform function is used.

The local transform function is useful for adding information to a specific endpoint, applying different transformations, or ignoring the global transform function.

The global transform function can be disabled by passing false instead of a function.

Transform Object

By passing a synchronous transformObject function you can modify the resulting swaggerObject or openapiObject before it is rendered.

1await fastify.register(require('@fastify/swagger'), {
2  swagger: { ... },
3  transformObject ({ swaggerObject }) => {
4    swaggerObject.info.title = 'Transformed';
5    return swaggerObject;
6  }
7})

Managing your $refs

In dynamic mode, this plugin resolves all $refs in the application's schemas, creating a new in-line schema that references itself. This ensures the generated documentation is valid, preventing Swagger UI from failing to fetch schemas from the server or network.

By default, this option resolves all $refs, renaming them to def-${counter}, while view models keep the original $id naming using the title parameter.

This logic can be customized by passing a refResolver option to the plugin:

1await fastify.register(require('@fastify/swagger'), {
2  swagger: { ... },
3  ...
4  refResolver: {
5    buildLocalReference (json, baseUri, fragment, i) {
6      return json.$id || `my-fragment-${i}`
7    }
8  }
9}

For details on buildLocalReference arguments, see the documentation.

Decorator

The default decorate function (fastify.swagger()) can be overridden by passing a string to the decorator option. This allows creating multiple documents by registering @fastify/swagger multiple times with different transform functions:

1// Create an internal Swagger doc
2await fastify.register(require('@fastify/swagger'), {
3  swagger: { ... },
4  transform: ({ schema, url, route, swaggerObject }) => {
5    const {
6      params,
7      body,
8      querystring,
9      headers,
10      response,
11      ...transformedSchema
12    } = schema
13    let transformedUrl = URL
14
15    // Hide external URLs
16    if (url.startsWith('/external')) transformedSchema.hide = true
17
18    return { schema: transformedSchema, url: transformedUrl }
19  },
20  decorator: 'internalSwagger'
21})
22
23// Create an external Swagger doc
24await fastify.register(require('@fastify/swagger'), {
25  swagger: { ... },
26  transform: ({ schema, url, route, swaggerObject }) => {
27    const {
28      params,
29      body,
30      querystring,
31      headers,
32      response,
33      ...transformedSchema
34    } = schema
35    let transformedUrl = URL
36
37    // Hide internal URLs
38    if (url.startsWith('/internal')) transformedSchema.hide = true
39
40    return { schema: transformedSchema, url: transformedUrl }
41  },
42  decorator: 'externalSwagger'
43})

Then call those decorators individually to retrieve them:

fastify.internalSwagger()
fastify.externalSwagger()

Route options

HEAD routes can be included in the definitions by adding exposeHeadRoute in the route config:

1  fastify.get('/with-head', {
2    schema: {
3      operationId: 'with-head',
4      response: {
5        200: {
6          description: 'Expected Response',
7          type: 'object',
8          properties: {
9            foo: { type: 'string' }
10          }
11        }
12      }
13    },
14    config: {
15      swagger: {
16        exposeHeadRoute: true,
17      }
18    }
19  }, () => {})

Response Options

Response description and response body description

description is required by the Swagger specification. If not provided, the plugin defaults to 'Default Response'. If a description is supplied, it will be used for both the response and response body schema:

1fastify.get('/description', {
2  schema: {
3    response: {
4      200: {
5        description: 'response and schema description',
6        type: 'string'
7      }
8    }
9  }
10}, () => {})

Generates this in a Swagger (OpenAPI v2) schema's paths:

1{
2  "/description": {
3    "get": {
4      "responses": {
5        "200": {
6          "description": "response and schema description",
7          "schema": {
8            "description": "response and schema description",
9            "type": "string"
10          }
11        }
12      }
13    }
14  }
15}

And this in an OpenAPI v3 schema's paths:

1{
2  "/description": {
3    "get": {
4      "responses": {
5        "200": {
6          "description": "response and schema description",
7          "content": {
8            "application/json": {
9              "schema": {
10                "description": "response and schema description",
11                "type": "string"
12              }
13            }
14          }
15        }
16      }
17    }
18  }
19}

To provide different descriptions for the response and response body, use the x-response-description field alongside description:

1fastify.get('/responseDescription', {
2  schema: {
3    response: {
4      200: {
5        'x-response-description': 'response description',
6        description: 'schema description',
7        type: 'string'
8      }
9    }
10  }
11}, () => {})

If a $ref is provided in the response schema without a description, the reference's description will be used as a fallback. Currently, $ref is resolved by matching with $id only, not through complex paths.

Status code 2xx

Fastify supports 2xx and 3xx status codes, but Swagger (OpenAPI v2) does not. @fastify/swagger transforms 2xx into 200, omitting it if 200 is already declared. OpenAPI v3 supports 2xx syntax so is unaffected.

Example:

1{
2  response: {
3    '2xx': {
4      description: '2xx',
5      type: 'object'
6    }
7  }
8}
9
10// will become
11{
12  response: {
13    200: {
14      schema: {
15        description: '2xx',
16        type: 'object'
17      }
18    }
19  }
20}

Response headers

Response headers can be decorated with the following example. Specify the type property when decorating response headers to prevent schema modification by Fastify.

1{
2  response: {
3    200: {
4      type: 'object',
5      headers: {
6        'X-Foo': {
7          type: 'string'
8        }
9      }
10    }
11  }
12}

Different content types responses

🛈 Note: Supported only by OpenAPI v3, not Swagger (OpenAPI v2).

Different content types are supported by @fastify/swagger and @fastify. Use content for the response to prevent Fastify from failing to compile the schema:

1{
2  response: {
3    200: {
4      description: 'Description and all status-code based properties are working',
5      content: {
6        'application/json': {
7          schema: {
8            name: { type: 'string' },
9            image: { type: 'string' },
10            address: { type: 'string' }
11          }
12        },
13        'application/vnd.v1+json': {
14          schema: {
15            fullName: { type: 'string' },
16            phone: { type: 'string' }
17          }
18        }
19      }
20    }
21  }
22}

Empty Body Responses

Empty body responses are supported by @fastify/swagger. Specify type: 'null' for the response to prevent Fastify from failing to compile the schema:

1{
2  response: {
3    204: {
4      type: 'null',
5      description: 'No Content'
6    },
7    503: {
8      type: 'null',
9      description: 'Service Unavailable'
10    }
11  }
12}

OpenAPI Parameter Options

🛈 Note: OpenAPI's terminology differs from Fastify's. OpenAPI uses "parameter" to refer to parts of a request that in Fastify's validation documentation are called "querystring", "params", and "headers".

OpenAPI extends the JSON schema specification with options like collectionFormat for encoding array parameters.

These encoding options only affect how Swagger UI presents documentation and generates curl commands. Depending on the schema options, you may need to change Fastify's default query string parser to produce a JavaScript object conforming to the schema. The default parser conforms to collectionFormat: "multi". For collectionFormat: "csv", replace the default parser with one that parses CSV values into arrays. This applies to other request parts that OpenAPI calls "parameters" and are not encoded as JSON.

Different serialization style and explode can also be applied as specified here.

@fastify/swagger supports these options as shown in this example:

1// Need to add a collectionFormat keyword to ajv in fastify instance
2const fastify = Fastify({
3  ajv: {
4    customOptions: {
5      keywords: ['collectionFormat']
6    }
7  }
8})
9
10fastify.route({
11  method: 'GET',
12  url: '/',
13  schema: {
14    querystring: {
15      type: 'object',
16      required: ['fields'],
17      additionalProperties: false,
18      properties: {
19        fields: {
20          type: 'array',
21          items: {
22            type: 'string'
23          },
24          minItems: 1,
25          //
26          // Note that this is an OpenAPI version 2 configuration option. The
27          // options changed in version 3.
28          //
29          // Put `collectionFormat` on the same property which you are defining
30          // as an array of values. (i.e. `collectionFormat` should be a sibling
31          // of the `type: "array"` specification.)
32          collectionFormat: 'multi'
33        }
34      },
35     // OpenAPI 3 serialization options
36     explode: false,
37     style: "deepObject"
38    }
39  },
40  handler (request, reply) {
41    reply.send(request.query.fields)
42  }
43})

There is a complete runnable example here.

Complex serialization in query and cookie, eg. JSON

🛈 Note: Supported only by OpenAPI v3, not Swagger (OpenAPI v2).

http://localhost/?filter={"foo":"baz","bar":"qux"}

🛈 Note: Change Fastify's default query string parser to produce a JavaScript object conforming to the schema. See example.

1fastify.route({
2  method: 'GET',
3  url: '/',
4  schema: {
5    querystring: {
6      type: 'object',
7      required: ['filter'],
8      additionalProperties: false,
9      properties: {
10        filter: {
11          type: 'object',
12          required: ['foo'],
13          properties: {
14            foo: { type: 'string' },
15            bar: { type: 'string' }
16          },
17          'x-consume': 'application/json'
18        }
19      }
20    }
21  },
22  handler (request, reply) {
23    reply.send(request.query.filter)
24  }
25})

Generates this in the OpenAPI v3 schema's paths:

1{
2  "/": {
3    "get": {
4      "parameters": [
5        {
6          "in": "query",
7          "name": "filter",
8          "required": true,
9          "content": {
10            "application/json": {
11              "schema": {
12                "type": "object",
13                "required": [
14                  "foo"
15                ],
16                "properties": {
17                  "foo": {
18                    "type": "string"
19                  },
20                  "bar": {
21                    "type": "string"
22                  }
23                }
24              }
25            }
26          }
27        }
28      ]
29    }
30  }
31}

Route parameters

Route parameters in Fastify are called params. These are values included in the URL of the requests, for example:

1fastify.route({
2  method: 'GET',
3  url: '/:id',
4  schema: {
5    params: {
6      type: 'object',
7      properties: {
8        id: {
9          type: 'string',
10          description: 'user id'
11        }
12      }
13    }
14  },
15  handler (request, reply) {
16    reply.send(request.params.id)
17  }
18})

Generates this in the Swagger (OpenAPI v2) schema's paths:

1{
2  "/{id}": {
3    "get": {
4      "parameters": [
5        {
6          "type": "string",
7          "description": "user id",
8          "required": true,
9          "in": "path",
10          "name": "id"
11        }
12      ],
13      "responses": {
14        "200": {
15          "description": "Default Response"
16        }
17      }
18    }
19  }
20}

Generates this in the OpenAPI v3 schema's paths:

1{
2  "/{id}": {
3    "get": {
4      "parameters": [
5        {
6          "schema": {
7            "type": "string"
8          },
9          "in": "path",
10          "name": "id",
11          "required": true,
12          "description": "user id"
13        }
14      ],
15      "responses": {
16        "200": {
17          "description": "Default Response"
18        }
19      }
20    }
21  }
22}

When params is not present in the schema, or a schema is not provided, parameters are automatically generated:

1fastify.route({
2  method: 'POST',
3  url: '/:id',
4  handler (request, reply) {
5    reply.send(request.params.id)
6  }
7})

Generates this in the Swagger (OpenAPI v2) schema's paths:

1{
2  "/{id}": {
3    "get": {
4      "parameters": [
5        {
6          "type": "string",
7          "required": true,
8          "in": "path",
9          "name": "id"
10        }
11      ],
12      "responses": {
13        "200": {
14          "description": "Default Response"
15        }
16      }
17    }
18  }
19}

Generates this in the OpenAPI v3 schema's paths:

1{
2  "/{id}": {
3    "get": {
4      "parameters": [
5        {
6          "schema": {
7            "type": "string"
8          },
9          "in": "path",
10          "name": "id",
11          "required": true
12        }
13      ],
14      "responses": {
15        "200": {
16          "description": "Default Response"
17        }
18      }
19    }
20  }
21}

Links

🛈 Note: Supported only by OpenAPI v3, not Swagger (OpenAPI v2).

Add OpenAPI v3 Links by adding a links property to the top-level options of a route. See:

1fastify.get('/user/:id', {
2  schema: {
3    params: {
4      type: 'object',
5      properties: {
6        id: {
7          type: 'string',
8          description: 'the user identifier, as userId'
9        }
10      },
11      required: ['id']
12    },
13    response: {
14      200: {
15        type: 'object',
16        properties: {
17          uuid: {
18            type: 'string',
19            format: 'uuid'
20          }
21        }
22      }
23    }
24  },
25  links: {
26    // The status code must match the one in the response
27    200: {
28      address: {
29        // See the OpenAPI documentation
30        operationId: 'getUserAddress',
31        parameters: {
32          id: '$request.path.id'
33        }
34      }
35    }
36  }
37}, () => {})
38
39fastify.get('/user/:id/address', {
40  schema: {
41    operationId: 'getUserAddress',
42    params: {
43      type: 'object',
44      properties: {
45        id: {
46          type: 'string',
47          description: 'the user identifier, as userId'
48        }
49      },
50      required: ['id']
51    },
52    response: {
53      200: {
54        type: 'string'
55      }
56    }
57  }
58}, () => {})

Hide a route

There are two ways to hide a route from the Swagger UI:

• Pass { hide: true } to the schema object inside the route declaration.
• Use the tag declared in hiddenTag options property inside the route declaration. Default is X-HIDDEN.

Swagger function options

Registering @fastify/swagger decorates the fastify instance with fastify.swagger(), which returns a JSON object representing the API. If { yaml: true } is passed to fastify.swagger() it returns a YAML string.

Integration

This plugin can be integrated with @fastify/helmet with minimal effort:

1.register(helmet, instance => {
2  return {
3    contentSecurityPolicy: {
4      directives: {
5        ...helmet.contentSecurityPolicy.getDefaultDirectives(),
6        "form-action": ["'self'"],
7        "img-src": ["'self'", "data:", "validator.swagger.io"],
8        "script-src": ["'self'"].concat(instance.swaggerCSP.script),
9        "style-src": ["'self'", "https:"].concat(
10          instance.swaggerCSP.style
11        ),
12      }
13    }
14  }
15})

Add examples to the schema

OpenAPI and JSON Schema have different examples field formats.

Array with examples from JSON Schema converted to OpenAPI example or examples field automatically with generated names (example1, example2...):

1fastify.route({
2  method: 'POST',
3  url: '/',
4  schema: {
5    querystring: {
6      type: 'object',
7      required: ['filter'],
8      properties: {
9        filter: {
10          type: 'object',
11          required: ['foo'],
12          properties: {
13            foo: { type: 'string' },
14            bar: { type: 'string' }
15          },
16          examples: [
17            { foo: 'bar', bar: 'baz' },
18            { foo: 'foo', bar: 'bar' }
19          ]
20        }
21      },
22      examples: [
23        { filter: { foo: 'bar', bar: 'baz' } }
24      ]
25    }
26  },
27  handler (request, reply) {
28    reply.send(request.query.filter)
29  }
30})

Generates this in the OpenAPI v3 schema's paths:

1"/": {
2  "post": {
3    "requestBody": {
4      "content": {
5        "application/json": {
6          "schema": {
7            "type": "object",
8            "required": ["filter"],
9            "properties": {
10              "filter": {
11                "type": "object",
12                "required": ["foo"],
13                "properties": {
14                  "foo": { "type": "string" },
15                  "bar": { "type": "string" }
16                },
17                "example": { "foo": "bar", "bar": "baz" }
18              }
19            }
20          },
21          "examples": {
22            "example1": {
23              "value": { "filter": { "foo": "bar", "bar": "baz" } }
24            },
25            "example2": {
26              "value": { "filter": { "foo": "foo", "bar": "bar" } }
27            }
28          }
29        }
30      },
31      "required": true
32    },
33    "responses": { "200": { "description": "Default Response" } }
34  }
35}

Use the x-examples field to set names or add descriptions to schema examples in OpenAPI format:

1// Need to add a new allowed keyword to ajv in fastify instance
2const fastify = Fastify({
3  ajv: {
4    plugins: [
5      function (ajv) {
6        ajv.addKeyword({ keyword: 'x-examples' })
7      }
8    ]
9  }
10})
11
12fastify.route({
13  method: 'POST',
14  url: '/feed-animals',
15  schema: {
16    body: {
17      type: 'object',
18      required: ['animals'],
19      properties: {
20        animals: {
21          type: 'array',
22          items: {
23            type: 'string'
24          },
25          minItems: 1,
26        }
27      },
28      "x-examples": {
29        Cats: {
30          summary: "Feed cats",
31          description:
32            "A longer **description** of the options with cats",
33          value: {
34            animals: ["Tom", "Garfield", "Felix"]
35          }
36        },
37        Dogs: {
38          summary: "Feed dogs",
39          value: {
40            animals: ["Spike", "Odie", "Snoopy"]
41          }
42        }
43      }
44    }
45  },
46  handler (request, reply) {
47    reply.send(request.body.animals)
48  }
49})

$id and $ref usage

How to work with $refs

The /docs/json endpoint in dynamic mode produces a single swagger.json file, resolving all of the references.

Acknowledgments

This project is kindly sponsored by:

• nearForm
• LetzDoIt

License

Licensed under MIT.