---
name: generate-client
description: >
  Run the @bazo/openapi-client-generator CLI to produce a typed API client
  from an OpenAPI JSON spec. Covers CLI flags (-n/--name, -m/--mode,
  --namespace, --php-version, --token-scope, --package, --lenient-enums, --schemas, --operations, --overlay), positional arguments (spec path, output
  directory), generation modes (full, playwright, backend, swift, kotlin,
  php, php-legacy, go, zod) and when to choose each,
  output file naming, and npm script integration. Load when generating,
  regenerating, or configuring the openapi-client-generator CLI.
type: core
library: openapi-client-generator
library_version: "3.0.0"
sources:
  - "bazo/openapi-client-generator:src/bin.ts"
  - "bazo/openapi-client-generator:src/pipeline.ts"
  - "bazo/openapi-client-generator:src/parser/overlay.ts"
  - "bazo/openapi-client-generator:src/parser/select-operations.ts"
---

# Generate Client

## Setup

```bash
npm install -D @bazo/openapi-client-generator
```

Run the generator:

```bash
npx openapi-client api.json out/ -n MyClient -m full
```

Arguments and flags:

| Position/Flag | Required | Description |
| --- | --- | --- |
| `<spec.json>` | yes | Path to a local OpenAPI JSON file |
| `<output-dir>` | yes | Directory for the generated file |
| `-n, --name` | yes | Client class name (must be a valid TypeScript identifier) |
| `-m, --mode` | no | `full` (default), `playwright`, `backend`, `swift`, `kotlin`, `php`, `php-legacy`, or `go` |
| `--namespace` | no | php, php-legacy: root PHP namespace (default: `--name`). swift: wrap the whole client in `enum <ns>` |
| `--php-version` | no | Target PHP version. php mode: `8.0`–`8.5` (default: `8.1`). php-legacy mode: `7.3` or `7.4` (default: `7.3`) |
| `--token-scope` | no | php-legacy only: scope for the generated `Auth\ClientCredentials` when the spec declares no OAuth2 scheme (overrides the scheme's first scope) |
| `--package` | no | Go package name (go mode only, default: `--name` lowercased) |
| `--lenient-enums` | no | go mode only: decode undeclared enum values (kept raw; `Valid()` is `false`) instead of failing the response |
| `--operations` | no | Only these operations: comma-separated operationIds or `"METHOD /path"`, repeatable. Unreached components are dropped; an unknown selector is an error |
| `--overlay` | no | An OpenAPI Overlay 1.0 file (JSON/YAML) applied to the spec first; repeatable, in order |

Save as an npm script:

```json
{
  "scripts": {
    "generate-api": "openapi-client api.json src/generated/ -n ApiClient -m full"
  }
}
```

## Input

The spec is a local JSON or YAML file in OpenAPI 3.0, 3.1 or **Swagger 2.0**. A Swagger 2.0 document (Forgejo and
Gitea publish nothing else) is lifted to OpenAPI 3.0 before generation, so it gets the same typed
models, parameters and responses as a 3.x spec. Recursive schemas — a schema that refers to itself,
or a cycle through several — are supported in every mode.

## Choosing a mode

| Code that calls the API | Mode |
| --- | --- |
| React or React Native / Expo app (hooks, caching) | `full` |
| Server-side TypeScript — Node ≥ 18, Bun, Deno: BFFs, services, workers, SDK packages | `backend` |
| Playwright E2E / API tests | `playwright` |
| iOS / macOS | `swift` |
| Android / JVM | `kotlin` |
| PHP 8 (Symfony HttpClient) | `php` |
| PHP 7.3/7.4, no Composer (ext-curl only) | `php-legacy` |
| Go | `go` |

`full` requires `@tanstack/react-query` and a `QueryClient` even for a plain call, so do not use it
in server code: `backend` has the same Zod-validated models and request encoding with `zod` as its
only dependency and the platform `fetch` for HTTP.

## Core Patterns

### Generate a full-mode TypeScript client (React Query + Wretch + Zod)

```bash
npx openapi-client openapi.json src/api/ -n ApiClient -m full
```

Produces `src/api/ApiClient.ts` with Zod schemas, React Query hooks, and a client class.

### Generate a Playwright test client

```bash
npx openapi-client openapi.json tests/api/ -n TestApi -m playwright
```

Produces `tests/api/TestApi.ts` with async methods wrapping Playwright's `APIRequestContext`.

### Generate a backend (server-side) TypeScript client

```bash
npx openapi-client openapi.json src/api/ -n ApiClient -m backend
```

Produces `src/api/ApiClient.ts`: Zod schemas and a class with one async method per operation over
the platform `fetch` — `new ApiClient(baseUrl?, { fetch?, headers? })`. Only `zod` is needed at
runtime.

### Generate a Swift client

```bash
npx openapi-client openapi.json Sources/API/ -n ApiClient -m swift
```

Produces `Sources/API/ApiClient.swift` with Codable structs and URLSession-based async methods.

### Generate a Kotlin client

```bash
npx openapi-client openapi.json src/main/kotlin/api/ -n ApiClient -m kotlin
```

Produces `src/main/kotlin/api/ApiClient.kt` with `@Serializable` data classes and Ktor suspend functions.

### Generate a PHP client

```bash
npx openapi-client openapi.json src/Api/ -n ApiClient -m php --namespace "App\\Api" --php-version 8.2
```

Unlike the other modes, php outputs a directory: `src/Api/ApiClient/` with `ApiClient.php`, `Model/*.php`, `ApiResponse.php`, `ApiException.php`, and `SerializerFactory.php` (Symfony HttpClient + Serializer). `--php-version` gates emitted language features (enums/readonly 8.1+, readonly classes 8.2+, `#[\NoDiscard]` 8.5).

### Generate a PHP 7.3 client (no Composer)

```bash
npx openapi-client spec/sync.openapi.json clients/php -n MedelySyncClient -m php-legacy --namespace 'Medely\Client' --php-version 7.3
```

php-legacy writes `README.md` and `src/` **directly into the output directory** (not `<out>/<name>/`): one class per file, ext-curl + ext-json only. `Auth\ClientCredentials` is generated from the spec's OAuth2 `clientCredentials` security scheme; without one, from the operation whose path ends in `/token` with `--token-scope`.

### Generate a Go client

```bash
npx openapi-client openapi.json internal/ -n PetStore -m go --package petstore
```

Like php, go outputs a directory: `internal/PetStore/` holding one package (`package petstore`) of seven files — `client.go`, `runtime.go`, `errors.go`, `models.go`, `enums.go`, `unions.go`, `operations.go`. Standard library only (`net/http`, `encoding/json`), Go 1.27+. No `go.mod` is written: the package lives inside your module. The files are already gofmt-formatted.

## Vendor specs

For a large third-party API, generate only the operations you call and fix the spec's gaps with an
overlay rather than hand-editing a downloaded copy:

```bash
npx openapi-client vendor.yaml src/vendor -n VendorClient -m backend \
  --operations sendSms,getAccount --overlay vendor.overlay.yaml
```

Typical overlay fixes: add a `default` response (`$ref` to the vendor's error model) to every
operation so undocumented statuses (401/403/5xx) are parsed instead of returned as `data: null`;
`remove: true` a closed error-code `enum` the vendor keeps growing. Overlay targets are JSONPath
over the document as written (Swagger 2.0 before conversion, `$ref`s unresolved). Commit the spec
snapshot and the overlay next to the generated client so regeneration is reproducible.

## Common Mistakes

### CRITICAL Hallucinating non-existent CLI flags

Wrong:

```bash
npx openapi-client api.json out/ -n MyClient --format json --validate --strict
```

Correct:

```bash
npx openapi-client api.json out/ -n MyClient -m full
```

The CLI uses `parseArgs` with `strict: true`. Only `-n/--name`, `-m/--mode`, `--namespace`, `--php-version`, `--token-scope`, `--package`, `--lenient-enums`, `--operations`, `--overlay`, `-v/--version`, and `-h/--help` exist. Any other flag causes a hard error.

Source: src/bin.ts

### HIGH Wrong positional argument order

Wrong:

```bash
npx openapi-client out/ api.json -n MyClient
```

Correct:

```bash
npx openapi-client api.json out/ -n MyClient
```

The first positional must be the spec file path, the second must be the output directory. Swapping them causes the tool to try reading a directory as a JSON file.

Source: src/bin.ts

### HIGH Omitting the required --name flag

Wrong:

```bash
npx openapi-client api.json out/ -m full
```

Correct:

```bash
npx openapi-client api.json out/ -n MyClient -m full
```

The `-n/--name` flag is required. It sets the exported class name and output filename. The CLI exits with an error if missing.

Source: src/bin.ts

### HIGH Passing a URL instead of a local file

Wrong:

```bash
npx openapi-client https://api.example.com/openapi.yaml out/ -n MyClient
```

Correct:

```bash
curl -o openapi.yaml https://api.example.com/openapi.yaml
npx openapi-client ./openapi.yaml out/ -n MyClient
```

The parser expects a local file path (JSON or YAML). Download a remote spec first — and commit it,
so the client can be regenerated from the same contract.

Source: src/parser/openapi-parser.ts

### HIGH Using an invalid mode name

Wrong:

```bash
npx openapi-client api.json out/ -n MyClient -m react-query
```

Correct:

```bash
npx openapi-client api.json out/ -n MyClient -m full
```

Mode must be exactly `full`, `playwright`, `backend`, `swift`, `kotlin`, `php`, `php-legacy`, or `go`. Aliases like `react-query`, `ts`, `node`, `server`, `ios`, `android`, `symfony`, or `golang` are not recognized.

Source: src/bin.ts

See also: integrate-full-client/SKILL.md — peer deps and client instantiation for full mode
See also: integrate-playwright-client/SKILL.md — Playwright fixture setup for playwright mode
See also: integrate-backend-client/SKILL.md — options, headers, fetch injection and responses for backend mode
See also: integrate-swift-client/SKILL.md — Xcode integration for swift mode
See also: integrate-kotlin-client/SKILL.md — Ktor setup for kotlin mode
See also: integrate-php-client/SKILL.md — Composer setup and Symfony HttpClient integration for php mode
See also: integrate-php-legacy-client/SKILL.md — loading, auth, token cache and errors of the PHP 7.3 client
See also: integrate-go-client/SKILL.md — calling the Go client and handling its typed errors
See also: integrate-zod-schemas/SKILL.md — schemas-only Zod output, --schemas closure, discriminated unions
