fastify-zod-openapi
Version:
Fastify plugin for zod-openapi
156 lines (149 loc) • 6.39 kB
text/typescript
import { FastifyTypeProvider, FastifyPluginAsync, FastifyPluginOptions, RawServerBase, RawServerDefault, FastifyPluginCallback, FastifySchema, FastifySchemaCompiler } from 'fastify';
import * as z from 'zod/v4';
import { ZodError, ZodType } from 'zod/v4';
import { ZodOpenApiComponentsObject, CreateDocumentOptions, oas31, ZodOpenApiRequestBodyObject, ZodOpenApiResponsesObject, ZodObjectInput } from 'zod-openapi';
import { ComponentRegistry } from 'zod-openapi/api';
import * as _fastify_error from '@fastify/error';
import { FastifySchemaValidationError, FastifySerializerCompiler } from 'fastify/types/schema';
import * as core from 'zod/v4/core';
import { $ZodType } from 'zod/v4/core';
import * as _fastify_swagger from '@fastify/swagger';
import { FastifyDynamicSwaggerOptions } from '@fastify/swagger';
declare class RequestValidationError extends Error implements FastifySchemaValidationError {
keyword: core.$ZodIssueCode;
instancePath: string;
schemaPath: string;
message: string;
params: {
issue: core.$ZodIssue;
error: ZodError;
};
cause: core.$ZodIssue;
constructor(keyword: core.$ZodIssueCode, instancePath: string, schemaPath: string, message: string, params: {
issue: core.$ZodIssue;
error: ZodError;
});
}
declare const ResponseSerializationError_base: _fastify_error.FastifyErrorConstructor<{
code: "FST_ERR_RESPONSE_SERIALIZATION";
statusCode: 500;
}, [any?, any?, any?]>;
declare class ResponseSerializationError extends ResponseSerializationError_base {
method: string;
url: string;
cause: ZodError;
constructor(method: string, url: string, options: {
cause: ZodError;
});
}
declare const FASTIFY_ZOD_OPENAPI_CONFIG: unique symbol;
interface FastifyZodOpenApiOpts {
components?: ZodOpenApiComponentsObject;
documentOpts?: CreateDocumentOptions;
}
interface FastifyZodOpenApiConfig {
registry: ComponentRegistry;
documentOpts?: CreateDocumentOptions;
fastifyComponents: {
responses: Map<string, {
referenceObject: oas31.ReferenceObject;
path: string[];
}>;
requestBodies: Map<string, {
referenceObject: oas31.ReferenceObject;
path: string[];
}>;
};
}
declare module 'fastify' {
interface FastifySchema {
[FASTIFY_ZOD_OPENAPI_CONFIG]?: FastifyZodOpenApiConfig;
}
interface FastifyValidationResult {
errors?: RequestValidationError[];
}
}
declare module 'openapi-types' {
namespace OpenAPIV3 {
interface Document {
[FASTIFY_ZOD_OPENAPI_CONFIG]?: FastifyZodOpenApiConfig;
}
}
}
interface FastifyZodOpenApiTypeProvider extends FastifyTypeProvider {
validator: this['schema'] extends ZodType ? z.infer<this['schema']> : this['schema'] extends ZodOpenApiRequestBodyObject ? this['schema']['content'] extends Record<string, {
schema: ZodType;
}> ? z.infer<this['schema']['content'][keyof this['schema']['content']]['schema']> : unknown : unknown;
serializer: this['schema'] extends ZodType ? z.input<this['schema']> : unknown;
}
type FastifyZodOpenApi = FastifyPluginAsync<FastifyZodOpenApiOpts>;
declare const fastifyZodOpenApiPlugin: FastifyZodOpenApi;
/**
* FastifyPluginCallbackZodOpenApi with Zod automatic type inference
*
* @example
* ```typescript
* import { FastifyPluginCallbackZodOpenApi } from "fastify-zod-openapi"
*
* const plugin: FastifyPluginCallbackZodOpenApi = (fastify, options, done) => {
* done()
* }
* ```
*/
type FastifyPluginCallbackZodOpenApi<Options extends FastifyPluginOptions = Record<never, never>, Server extends RawServerBase = RawServerDefault> = FastifyPluginCallback<Options, Server, FastifyZodOpenApiTypeProvider>;
/**
* FastifyPluginAsyncZodOpenApi with Zod automatic type inference
*
* @example
* ```typescript
* import { FastifyPluginAsyncZodOpenApi } from "fastify-zod-openapi"
*
* const plugin: FastifyPluginAsyncZodOpenApi = async (fastify, options) => {
* }
* ```
*/
type FastifyPluginAsyncZodOpenApi<Options extends FastifyPluginOptions = Record<never, never>, Server extends RawServerBase = RawServerDefault> = FastifyPluginAsync<Options, Server, FastifyZodOpenApiTypeProvider>;
interface SerializerOptions {
components?: Record<string, $ZodType>;
stringify?: (value: unknown) => string;
fallbackSerializer?: FastifySerializerCompiler<$ZodType>;
}
declare const createSerializerCompiler: (opts?: SerializerOptions) => FastifySerializerCompiler<$ZodType>;
/**
* Enables zod-openapi schema response validation
*
* @example
* ```typescript
* import Fastify from 'fastify'
*
* const server = Fastify().setSerializerCompiler(serializerCompiler)
* ```
*/
declare const serializerCompiler: FastifySerializerCompiler<$ZodType<unknown, unknown, core.$ZodTypeInternals<unknown, unknown>>>;
type Transform = NonNullable<FastifyDynamicSwaggerOptions['transform']>;
type TransformObject = NonNullable<FastifyDynamicSwaggerOptions['transformObject']>;
type FastifyZodOpenApiSchema = Omit<FastifySchema, 'response' | 'headers' | 'querystring' | 'body' | 'params'> & {
response?: ZodOpenApiResponsesObject;
headers?: ZodObjectInput;
querystring?: ZodObjectInput;
body?: $ZodType | ZodOpenApiRequestBodyObject;
params?: ZodObjectInput;
};
declare const fastifyZodOpenApiTransform: Transform;
declare const fastifyZodOpenApiTransformObject: TransformObject;
declare const fastifyZodOpenApiTransformers: {
transform: _fastify_swagger.SwaggerTransform<FastifySchema>;
transformObject: _fastify_swagger.SwaggerTransformObject;
};
/**
* Enables zod-openapi schema validation
*
* @example
* ```typescript
* import Fastify from 'fastify'
*
* const server = Fastify().setValidatorCompiler(validatorCompiler)
* ```
*/
declare const validatorCompiler: FastifySchemaCompiler<ZodType>;
export { FASTIFY_ZOD_OPENAPI_CONFIG, type FastifyPluginAsyncZodOpenApi, type FastifyPluginCallbackZodOpenApi, type FastifyZodOpenApi, type FastifyZodOpenApiOpts, type FastifyZodOpenApiSchema, type FastifyZodOpenApiTypeProvider, RequestValidationError, ResponseSerializationError, type SerializerOptions, createSerializerCompiler, fastifyZodOpenApiPlugin, fastifyZodOpenApiTransform, fastifyZodOpenApiTransformObject, fastifyZodOpenApiTransformers, serializerCompiler, validatorCompiler };