@fohoov/zod-openapi-client NPM

TypeScript Client Generator CLI

A powerful command-line tool for generating TypeScript API clients and Zod schemas directly from your OpenAPI specifications. This CLI leverages the OpenApiTools engine to create robust clients in both object-oriented (OOP) and functional styles, and it also produces Zod schemas for runtime type validation using openapi-zod-client (credit to astahmer).

Features

Generate TypeScript Clients:
Automatically create clients that match your OpenAPI specs in two modes:
- OOP Mode (default): Generates object-oriented clients.
- Functional Mode: Generates functional clients using customized templates from /public/templates.
Zod Schema Generation:
In addition to client generation, this CLI also creates Zod schemas from your API types for runtime type validation. This feature uses the openapi-zod-client (credit to astahmer).
HTTP Client Options:
Choose between:
- fetch (default)
- axios (with configurable axios version)
Endpoint Customization:
Remove prefixes from endpoints and apply regex-based replacements to clean up your API paths.
Operation ID Customization:
Modify and format operation IDs based on your requirements using customizable formatters.
Flexible Configuration:
Set output directories, skip spec validations, and more with simple CLI options.

Prerequisites

Java:
OpenApiTools requires Java. Ensure you have it installed. Download Java
Node.js & PNPM:
Make sure Node.js is installed. We recommend using pnpm as your package manager.
Install the @openapitools/openapi-generator-cli npm package

Installation

Install the CLI via pnpm:

pnpm i @fohoov/zod-openapi-client

Or run it without installing using:

pnpm dlx @fohoov/zod-openapi-client --help

Usage

To generate a client and corresponding Zod schemas, you must provide the URL of your OpenAPI JSON spec along with optional configuration options.

Basic Command

pnpm exec client-generator --uri <your-openapi-spec-url>

By default, this command will generate an OOP client using the fetch library, create corresponding Zod schemas, and output the generated files to src/generated-clients.

CLI Options

Here’s a breakdown of the available options:

--uri <uri>
The URL to the OpenAPI JSON specification.
Required. You can also set this via the OPENAPI_URL environment variable.
--mode <string>
Choose the client generation mode:
- oop (default) – Generates an object-oriented client.
- functional – Generates a functional client using templates from /public/templates.
  if mode is set to functional the /[generated-path]/base.ts file exports a functional called updateGlobalConfiguration to set your configurations globally
--client <string>
Select the HTTP client library:
- fetch (default)
- axios
--axios-version <string>
Specify the axios version to use (applicable only if --client is set to axios).
Default: "1.7.0"
--out <string>
The output directory for the generated client and schema files.
Default: "src/generated-clients"
--remove-endpoint-prefix <string>
Remove a specified prefix from endpoints (e.g., convert /x/path to /path).
--replace-endpoint-regex <pair...>
Apply a regex replacement on endpoints before prefix removal.
Example: --replace-endpoint-regex /api/,/account-report-service/
--skip-spec-validations <boolean>
Skip OpenAPI specification validations. Refer to OpenAPI Generator Configuration for details on skip-validate-spec.
--customize-operation-id <boolean>
Customize operation IDs using specific formatters. For instance, for a POST endpoint like /api/Account/inquiry-account-balance/{account}, you can use a formatter (e.g., m_ls_m:camelcase) to generate a new operation ID (like postInquiryAccountBalancePost).
Note: Existing operation IDs are ignored unless you also use --overwrite-existing-operation-ids.
Current available formatters: ${JSON.stringify(CUSTOM_OPERATION_COMMANDS)}
--overwrite-existing-operation-ids
Use in combination with --customize-operation-id to overwrite any existing operation IDs.

Additional Note:
These options might be outdated, to see current available options and their defaults use --help

Examples

1. Generate an OOP Client with Fetch and Zod Schemas

pnpm exec client-generator --uri "https://api.example.com/openapi.json" --mode oop --client fetch --out "./generated-client"

2. Generate a Functional Client with Axios, Custom Operation IDs, and Zod Schemas

pnpm exec client-generator --uri "https://api.example.com/openapi.json" --mode functional --client axios --axios-version "1.7.0"

3. Remove an Endpoint Prefix and Apply Regex Replacement

pnpm exec client-generator --uri "https://api.example.com/openapi.json" --remove-endpoint-prefix "/v1" --replace-endpoint-regex "/api/,/account-report-service/"