Package Exports

fastify-zod-openapi
fastify-zod-openapi/lib-commonjs/index.js
fastify-zod-openapi/lib-es2015/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-zod-openapi) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.

Credits

fastify-type-provider-zod: Big kudos to this library for lighting the way with how to create type providers, validators and serializers. fastify-zod-openapi is just an extension to this library whilst adding support for the functionality of zod-openapi.

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

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

To release a new beta version

Create a new GitHub Release
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.
Click the Generate release notes button and adjust the description.
Tick the Set as a pre-release box and click Publish release. This will trigger the Prerelease workflow.