fastify-zod-openapi

fastify-zod-openapi

Fastify type provider, validation, serialization and @fastify/swagger support for zod-openapi.

Install

Install via npm or yarn:

npm install zod zod-openapi fastify-zod-openapi
## or
yarn add zod zod-openapi fastify-zod-openapi

Usage

import fastify from 'fastify';
import {
  type FastifyZodOpenApiSchema,
  type FastifyZodOpenApiTypeProvider,
  fastifyZodOpenApiPlugin,
  serializerCompiler,
  validatorCompiler,
} from 'fastify-zod-openapi';
import { z } from 'zod';
import { extendZodWithOpenApi } from 'zod-openapi';

extendZodWithOpenApi(z);

const app = fastify();

app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

app.withTypeProvider<FastifyZodOpenApiTypeProvider>().route({
  method: 'POST',
  url: '/:jobId',
  schema: {
    body: z.string().openapi({
      description: 'Job ID',
      example: '60002023',
    }),
    response: {
      201: z.object({
        jobId: z.string().openapi({
          description: 'Job ID',
          example: '60002023',
        }),
      }),
    },
  } satisfies FastifyZodOpenApiSchema,
  handler: async (_req, res) =>
    res.send({
      jobId: '60002023',
    }),
});

await app.ready();
await app.listen({ port: 5000 });

Usage with @fastify/swagger

import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUI from '@fastify/swagger-ui';
import fastify from 'fastify';
import {
  type FastifyZodOpenApiSchema,
  type FastifyZodOpenApiTypeProvider,
  fastifyZodOpenApiPlugin,
  fastifyZodOpenApiTransform,
  fastifyZodOpenApiTransformObject,
  serializerCompiler,
  validatorCompiler,
} from 'fastify-zod-openapi';
import { z } from 'zod';
import { type ZodOpenApiVersion, extendZodWithOpenApi } from 'zod-openapi';

extendZodWithOpenApi(z);

const app = fastify();

app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);

const openapi: ZodOpenApiVersion = '3.0.3'; // If this is not specified, it will default to 3.1.0

await app.register(fastifyZodOpenApiPlugin, { openapi });
await app.register(fastifySwagger, {
  openapi: {
    info: {
      title: 'hello world',
      version: '1.0.0',
    },
    openapi,
  },
  transform: fastifyZodOpenApiTransform,
  transformObject: fastifyZodOpenApiTransformObject,
});
await app.register(fastifySwaggerUI, {
  routePrefix: '/documentation',
});

app.withTypeProvider<FastifyZodOpenApiTypeProvider>().route({
  method: 'POST',
  url: '/',
  schema: {
    body: z.string().openapi({
      description: 'Job ID',
      example: '60002023',
    }),
    response: {
      201: {
        content: {
          'application/json': {
            schema: z.object({
              jobId: z.string().openapi({
                description: 'Job ID',
                example: '60002023',
              }),
            }),
          },
        },
      },
    },
  } satisfies FastifyZodOpenApiSchema,
  handler: async (_req, res) =>
    res.send({
      jobId: '60002023',
    }),
});
await app.ready();
await app.listen({ port: 5000 });

Declaring Components

To declare components follow the documentation as declared here.

If you wish to declare the components manually you will need to do so via the plugin's options.

await app.register(fastifyZodOpenApiPlugin, {
  openapi,
  components: { schema: mySchema },
});

Please note: the responses, parameters components do not appear to be supported by the @fastify/swagger library.

Development

Prerequisites

• Node.js LTS
• Yarn 1.x

yarn
yarn build

Test

yarn test

Lint

# Fix issues
yarn format

# Check for issues
yarn lint

Release

To release a new version

1. Create a new GitHub Release
2. Select 🏷️ Choose a tag, enter a version number. eg. v1.2.0 and click + Create new tag: vX.X.X on publish.
3. Click the Generate release notes button and adjust the description.
4. Tick the Set as the latest release box and click Publish release. This will trigger the Release workflow.
5. Check the Pull Requests tab for a PR labelled Release vX.X.X.
6. Click Merge Pull Request on that Pull Request to update main with the new package version.

To release a new beta version

1. Create a new GitHub Release
2. Select 🏷️ Choose a tag, enter a version number with a -beta.X suffix eg. v1.2.0-beta.1 and click + Create new tag: vX.X.X-beta.X on publish.
3. Click the Generate release notes button and adjust the description.
4. Tick the Set as a pre-release box and click Publish release. This will trigger the Prerelease workflow.