Quick start

You need Node.js 22.18 or later (TypeScript config files are loaded with Node’s built-in type stripping) and a Swagger 2.0 or OpenAPI 3.x document, as a file or a URL.

1. Install swaggerz as a development dependency. The generated client does not depend on it.

   npm install --save-dev swaggerz

   The CLI is installed as swaggerz and as the shorter sz.

2. Create a config. init finds your specification, reads its version, and turns on hooks for the data-fetching library your package.json already depends on.

   npx swaggerz init

   swaggerz.config.ts

   import { defineConfig } from 'swaggerz';
   
   export default defineConfig({
     spec: {
       version: '3.0',
       input: './openapi.yaml',
     },
     output: {
       directory: './src/generated/api',
     },
   });

   Prefer JSON or YAML? npx swaggerz init --format yaml. Every option is in the config reference.

3. Generate the client.

   npx swaggerz generate

   src/generated/api/ for the petstore fixture: 35 files, 15 operations, 11 models

   • client.ts, index.tsthe client instance and the barrel
   • models/one module per model
   • pet/8 operations tagged “pet”
   • runtime/transport, serialization, errors: emitted, no dependency
   • store/4 operations tagged “store”
   • user/3 operations tagged “user”
   • .swaggerz-manifest.jsonthe files the generator owns, with their hashes

4. Configure the client and call the API. Every operation is a function you import by name.

   src/main.ts

   import { client, getPetById, isGetPetByIdApiError } from './generated/api';
   
   // Once, at startup.
   client.setConfig({
     baseUrl: 'https://petstore3.swagger.io/api/v3',
     auth: { api_key: () => sessionStorage.getItem('apiKey') ?? undefined },
   });
   
   try {
     const pet = await getPetById({ petId: 10 }, { timeout: 5_000 });
     console.log(pet.name);
   } catch (error) {
     // Checking the status narrows the body to that response's type.
     if (isGetPetByIdApiError(error) && error.status === 404) console.error(error.body.message);
     else throw error;
   }

5. Keep it in step. Regenerate when the specification changes, or let it happen while you work, and check it in CI:

   npx swaggerz generate --watch   # regenerate on every change
   npx swaggerz generate --check   # in CI: fail when the committed client is out of date

Where to go next

• Hooks: features: { query: true } adds TanStack Query hooks; see data fetching.
• Validation: features: { validation: 'zod' } checks responses at runtime; see validation.
• A specification you do not own needs fixes? Patch it with an overlay.
• Something does not work: npx swaggerz doctor, then troubleshooting.