Quickstart

This guide walks you through installing openapi-zod-ts and generating a typed fetch client from an OpenAPI spec. It takes about five minutes.

1. Install

   npm

   npm i -D openapi-zod-ts

   pnpm

   pnpm add -D openapi-zod-ts

   yarn

   yarn add -D openapi-zod-ts

2. Add a config file

   Create openapi-zod-ts.config.json in your project root:

   {
     "input_openapi": "./openapi.json",
     "output": "./src/api"
   }

   Point input_openapi at your spec file (JSON or YAML). The output directory is created if it does not exist.

   The two required fields:

   Field	Description
   input_openapi	Path to your OpenAPI 3.x spec (JSON or YAML)
   output	Directory to write the generated files

   Optional fields let you set a default baseUrl, enable Zod schemas (input_schema), or generate a server-side client factory (server_client: true). See the full options reference.

3. Run the generator

   npx openapi-zod-ts

   This writes the following files to ./src/api/:

   File	Contents
   models.ts	TypeScript interfaces for every schema in components.schemas
   client.ts	One typed async function per API operation, using native fetch
   client-config.ts	configureClient() and getConfig(): set base URL and auth once at startup
   index.ts	Barrel re-export of all three files above

4. Use the generated client

   Call configureClient once at app startup, then import typed functions anywhere:

   import { configureClient } from './src/api'
   import { listTasks, createTask, ApiError } from './src/api'
   
   // Call once at app startup (e.g. main.ts or App.tsx)
   configureClient({
     baseUrl: 'https://api.example.com',
     token: () => getAccessToken(), // sync or async, called per request
   })
   
   // Every function is fully typed: parameters, return type, and error shape
   const page = await listTasks({ status: 'pending', page: 1 })
   
   try {
     const task = await createTask({ title: 'Ship it' })
     console.log(task.id)
   } catch (err) {
     if (err instanceof ApiError) {
       console.error(err.status, err.body)
     }
   }

   Note

   Function and type names are derived directly from your spec’s operation IDs and schema names. A GET /tasks operation with operationId: listTasks becomes async function listTasks(...).

What next?

You have a fully typed fetch client. Layer in hooks, a server interface, or error mapping as your project grows:

React Query hooks

Generate useQuery and useMutation hooks on top of this client.

openapi-react-query guide

Server interface

Generate a typed service interface and optional Hono, Express, or Fastify router.

openapi-server guide

Form error mapping

Map ApiError responses from mutation hooks directly to form field errors.

api-errors guide

MSW mocks

Generate seeded MSW v2 handlers from the same spec, so tests and local dev hit realistic mock data.

openapi-msw guide

Full-stack tutorial

See the generators and api-errors working together in the petstore-fastify demo.

Full-stack tutorial