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/"

Contributing

Contributions are very welcome! If you have suggestions, issues, or improvements, please feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.