Fastify plugin for zod-openapi
MIT License
Install via npm
, pnpm
or pnpm
:
npm install zod zod-openapi fastify-zod-openapi
## or
pnpm add zod zod-openapi fastify-zod-openapi
## or
pnpm install zod-openapi fastify-zod-openapi
import 'zod-openapi/extend';
import fastify from 'fastify';
import {
type FastifyZodOpenApiSchema,
type FastifyZodOpenApiTypeProvider,
serializerCompiler,
validatorCompiler,
} from 'fastify-zod-openapi';
import { z } from 'zod';
const app = fastify();
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
app.withTypeProvider<FastifyZodOpenApiTypeProvider>().route({
method: 'POST',
url: '/:jobId',
schema: {
body: z.object({
jobId: 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) => {
await res.send({ jobId: req.body.jobId });
},
});
await app.ready();
await app.listen({ port: 5000 });
import 'zod-openapi/extend';
import { FastifyPluginAsyncZodOpenApi } from 'fastify-zod-openapi';
import { z } from 'zod';
const plugin: FastifyPluginAsyncZodOpenApi = async (fastify, _opts) => {
fastify.route({
method: 'POST',
url: '/',
// Define your schema
schema: {
body: z.object({
jobId: 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) => {
await res.send({ jobId: req.body.jobId });
},
});
};
app.register(plugin);
import 'zod-openapi/extend';
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 } from 'zod-openapi';
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 });
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.
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.
pnpm install
pnpm build
pnpm test
# Fix issues
pnpm format
# Check for issues
pnpm lint
To release a new version
🏷️ Choose a tag
, enter a version number. eg. v1.2.0
and click + Create new tag: vX.X.X on publish
.Generate release notes
button and adjust the description.Set as the latest release
box and click Publish release
. This will trigger the Release
workflow.Pull Requests
tab for a PR labelled Release vX.X.X
.Merge Pull Request
on that Pull Request to update main with the new package version.To release a new beta version
🏷️ 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
.Generate release notes
button and adjust the description.Set as a pre-release
box and click Publish release
. This will trigger the Prerelease
workflow.