@uvisoft/zod-openapi-validator

Generate Zod validators and typed API client types from an OpenAPI 3 schema.

This package gives you a CLI for code generation and exports generator utilities for programmatic use.

Install

npm install --save-dev @uvisoft/zod-openapi-validator zod

Quick Start (CLI)

Generate files from an OpenAPI JSON document:

npx schema-generator generate \
	--input ./openapi.json \
	--output ./src/generated

Generated files:

• validation.ts: Zod schemas and inferred types
• httpClient.ts: OpenAPI-derived API types

CLI Command

schema-generator generate [options]

Options:

• -i, --input <path-or-url>: OpenAPI JSON input path (local file or URL)
• -o, --output <dir>: output directory
• -c, --config <path>: optional config file (default: ./schema-generator.config.json)

Config File

If config is present, values there override CLI options.

Example schema-generator.config.json:

{
	"input": "./openapi.json",
	"output": "./src/generated"
}

Using Generated Validators

The generator outputs z-prefixed schema variables and matching inferred types.

import { zLoginRequest } from "./generated/validation";

const payload = {
	email: "[email protected]",
	password: "secret"
};

const result = zLoginRequest.safeParse(payload);
if (!result.success) {
	console.error(result.error.format());
}

Programmatic Usage

You can run generation directly in Node.js:

import { readFile, saveFile, ZodGenerator } from "@uvisoft/zod-openapi-validator/generator";

const raw = await readFile("./openapi.json");
const openApi = JSON.parse(raw);
const zodCode = await new ZodGenerator(openApi).generate();

await saveFile("./src/generated/validation.ts", zodCode);

Notes

• Supports OpenAPI schema composition (allOf, anyOf, oneOf)
• Handles references and circular references
• Produces both runtime validators and static TypeScript types

Requirements

• Node.js 24+