# @bazo/openapi-client-generator

Generate type-safe API clients from an OpenAPI / Swagger JSON spec. One CLI, seven output targets:

| Mode | Output | Stack |
|------|--------|-------|
| `full` *(default)* | `.ts` | React Query hooks + [Wretch](https://github.com/elbywan/wretch) HTTP client + [Zod](https://zod.dev) validation |
| `playwright` | `.ts` | Class wrapping Playwright's `APIRequestContext` for E2E tests + Zod validation |
| `backend` | `.ts` | Server-side class over the platform `fetch` + Zod validation — Node ≥ 18, Bun, Deno; no React Query, no React |
| `swift` | `.swift` | `Codable` structs + `async/await` client (Foundation only) |
| `kotlin` | `.kt` | `@Serializable` data classes + Ktor-based suspend client |
| `php` | directory of `.php` | PSR-4 classes + backed enums + Symfony HttpClient/Serializer client |
| `zod` | `<name>.ts` | Only the component schemas as Zod 4 schemas plus `z.infer` types, in dependency order; no client. `--schemas` narrows it to chosen schemas and what they reference |
| `php-legacy` | `README.md` + `src/**.php` | PHP 7.3/7.4 client: no Composer, no dependencies, ext-curl transport, one class per file, exceptions, OAuth2 `client_credentials` authenticator |
| `go` | directory of `.go` | Structs + typed enums/unions + `net/http` client with typed per-operation errors (stdlib only) |

The TypeScript modes emit **Zod 4** validators (`z.email()`, `z.iso.datetime()`, `z.int()`, `z.strictObject()`, getter-based recursion), so they need `zod` >= 4.

Schemas are normalized, sorted by dependency, and emitted with full types; unused declarations are stripped from TypeScript output automatically.

Input may be OpenAPI 3.0, 3.1, 3.2 or Swagger 2.0 — a 2.0 document is lifted to 3.0 first. From 3.2, the `QUERY` method and `additionalOperations` (any other method token) are generated as body-carrying calls in every mode, and an `in: querystring` parameter with an object schema is expanded into ordinary query parameters. Recursive schemas (a schema that refers to itself, or a cycle through several) are supported in every mode. The test suite generates every mode from Forgejo's published API (`src/__tests__/fixtures/forgejo.json`) as a real-world gate.

## Installation

```bash
npm install -D @bazo/openapi-client-generator
# or: bun add -d @bazo/openapi-client-generator
```

You can also run it without installing:

```bash
npx @bazo/openapi-client-generator api.json src/api -n MyClient
```

## Usage

```
openapi-client-generator <spec.json> <output-dir> -n <ClientName> [-m <mode>]
```

| Option | Description |
|--------|-------------|
| `<spec.json>` | Path to the OpenAPI/Swagger spec, JSON or YAML (positional, required) |
| `<output-dir>` | Directory to write the generated file into (positional, required) |
| `-n, --name` | Client/class name — must be a valid identifier (required) |
| `-m, --mode` | `full` \| `playwright` \| `backend` \| `swift` \| `kotlin` \| `php` \| `php-legacy` \| `go` \| `zod` (default: `full`) |
| `--namespace` | php, php-legacy: root PHP namespace (default: `--name`). swift: wrap the whole client in `enum <ns>` so no generated type lands at module scope |
| `--php-version` | Target PHP version. php mode: `8.0`–`8.5` (default: `8.1`). php-legacy mode: `7.3` or `7.4` (default: `7.3`; 7.4 only adds typed properties) |
| `--token-scope` | php-legacy only: the scope `Auth\ClientCredentials` requests. Normally taken from the spec's OAuth2 `clientCredentials` security scheme (its `tokenUrl` and first scope); without one, the authenticator is generated for the operation whose path ends in `/token` and uses this scope (none if omitted). An explicit value wins over the scheme |
| `--schemas` | zod mode only: comma-separated component schema names; the output holds those plus every schema they reference (default: all). Unknown names fail. Ignored with a warning in other modes |
| `--package` | Go package name, go mode only (default: `--name` lowercased) |
| `--lenient-enums` | go mode only: decode enum values the spec does not declare instead of failing the response (the raw value is kept and round-trips; `Valid()` still reports `false`). Default: strict |
| `--operations` | Generate only these operations: comma-separated operationIds (the spec's own, or the one the generator derives for an operation without one) or `"METHOD /path"`. Repeatable. Components no selected operation reaches are dropped, in every mode. An unknown selector is an error |
| `--overlay` | Apply an [OpenAPI Overlay 1.0](https://spec.openapis.org/overlay/v1.0.0) file (JSON or YAML) to the spec before generating. Repeatable; applied in order |
| `-v, --version` | Print version |
| `-h, --help` | Print help |

The output file is named after `--name` with the extension chosen by the mode (`MyClient.ts`, `ApiClient.swift`, `ApiClient.kt`). The `php` mode instead writes a directory named after `--name` containing one PSR-4 file per class, the `php-legacy` mode writes `README.md` and `src/` straight into the output directory, and the `go` mode a directory named after `--name` holding one Go package.

```bash
# React Query client
openapi-client-generator api.json src/api -n MyClient

# Playwright E2E client
openapi-client-generator api.json tests/api -n TestApi -m playwright

# Server-side (Node/Bun/Deno) client — BFFs, services, SDK packages
openapi-client-generator api.json src/api -n ApiClient -m backend

# Swift client
openapi-client-generator api.json Sources/Api -n ApiClient -m swift

# Kotlin client
openapi-client-generator api.json src/main/kotlin -n ApiClient -m kotlin

# PHP client
openapi-client-generator api.json src/Api -n ApiClient -m php --namespace "App\\Api" --php-version 8.2

# Go client
openapi-client-generator api.json internal -n PetStore -m go --package petstore
```

### Vendor specs: `--operations` and `--overlay`

A vendor API often has hundreds of endpoints of which you call five, and a spec with gaps you cannot
fix upstream. Generate only what you use, and patch the spec with an overlay instead of editing a
copy of it:

```bash
openapi-client-generator brevo.yaml src/brevo -n BrevoClient -m backend \
  --operations sendTransacSms,getAccount,"DELETE /contacts/{identifier}" \
  --overlay brevo.overlay.yaml
```

```yaml
# brevo.overlay.yaml — OpenAPI Overlay 1.0: JSONPath (RFC 9535) targets, applied in order
overlay: 1.0.0
info: { title: Brevo spec fixes, version: 1.0.0 }
actions:
  - description: Statuses the spec does not list (401, 403, 5xx) keep their error body
    target: $.paths.*.*.responses
    update:
      default: { $ref: "#/components/responses/errorModel" }
  - description: The error `code` enum is closed; Brevo adds codes without notice
    target: $.components.schemas.errorModel.properties.code.enum
    remove: true
```

An overlay applies to the document **as written** — before a Swagger 2.0 spec is converted (so it
targets `definitions`, not `components`) and before `$ref`s are resolved (so it can add or replace
them). `update` merges into each matched object (nested objects merge, anything else — arrays
included — is replaced) or appends to a matched array; `remove: true` deletes the match. An action
that matches nothing is reported as a warning: it is usually a typo, or a vendor spec that moved.

A handy `package.json` script:

```json
{
  "scripts": {
    "gen:api": "openapi-client-generator ./openapi.json ./src/api -n MyClient"
  }
}
```

## Generated client examples

### `full` — React Query

Peer dependencies: `zod`, `wretch`, `@tanstack/react-query`.

```typescript
import { QueryClient } from "@tanstack/react-query";
import { MyClient } from "./api/MyClient";

const queryClient = new QueryClient();
const api = new MyClient("https://api.example.com", queryClient);

function TaskList() {
  const { data, isLoading } = api.listTasks.useQuery({ page: 1, limit: 10 });
  const create = api.createTask.useMutation();
  // ...
}
```

Constructor: `new MyClient(baseUrl, queryClient, options?, onHttpConfigure?)`. Each operation exposes `query`/`mutation` (raw) and `useQuery`/`useMutation` (hooks); responses are typed as `ApiResponse<T>` and validated with Zod — every documented body strictly, successes and errors (exact, `4XX`-style range or `default`) alike; a body that breaks its schema throws `ResponseValidationError` carrying the status. The Suspense `fetch`/`queryOptions` path throws `ApiStatusError` for a documented error status whose body validates (`data`/`code` from the exact → range → `default` lookup) and `ResponseValidationError` for one whose body does not.

### `playwright` — E2E testing

Peer dependencies: `zod`, `@playwright/test`.

```typescript
import { test, expect } from "@playwright/test";
import { TestApi } from "./api/TestApi";

test("list tasks returns 200", async ({ request }) => {
  const api = new TestApi(request);
  const result = await api.listTasks({ page: 1, limit: 10 });
  expect(result.status).toBe(200);
  expect(result.data.items.length).toBeGreaterThan(0);
});
```

Constructor takes Playwright's `APIRequestContext` (the `{ request }` fixture). Operations are `async` methods returning a Zod-validated `ApiResponse<T>`; like `backend`, every documented body — success or error, exact, `4XX` range or `default` — is validated strictly, and a mismatch throws `ResponseValidationError` carrying the status.

### `backend` — Node / Bun / Deno

Peer dependency: `zod` only. HTTP goes through the platform `fetch` (Node ≥ 18, Bun, Deno) — no wretch, no TanStack Query, no React. Use it for server-side code: BFFs, services, and SDK packages that wrap an API; use `full` for React/React Native apps.

```typescript
import { ApiClient } from "./api/ApiClient";

const api = new ApiClient("https://api.example.com", {
  // Called per request, so a refreshed token is always picked up (a plain HeadersInit works too).
  headers: async () => ({ Authorization: `Bearer ${await tokens.current()}` }),
  // Optional: any fetch-compatible function — a stub in tests, a custom agent, instrumentation.
  fetch: (input, init) => fetch(input, init),
});

const res = await api.getTask({ taskId: "42" }, { signal: AbortSignal.timeout(5_000) });
if (res.status === 200 && res.data) {
  console.log(res.data.title); // typed as the 200 schema
} else if (res.status === 404 && res.data) {
  console.warn(res.data.message); // typed as the 404 schema
}
```

- **Constructor:** `new ApiClient(baseUrl, options?)`. When the spec declares `servers`, `baseUrl` defaults to the first one (`ApiClient.defaultBaseUrl`; all of them are on `ApiClient.servers`), so `new ApiClient()` and `new ApiClient(undefined, { headers })` work. A trailing `/` on `baseUrl` is ignored.
- **`ApiClientOptions`:** `fetch?: (input: string, init: RequestInit) => Promise<Response>` (defaults to the global `fetch`, looked up per request) and `headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>)` (sent on every request).
- **Operations:** `async <operationId>(params, requestInit?)`. `params` holds path, query and header params plus `body`, and defaults to `{}` when nothing in it is required. `requestInit` is `RequestOptions` — `{ signal?: AbortSignal; headers?: HeadersInit }`.
- **Responses:** `ApiResponse<T, S>` — `{ data, status, headers: Headers, url }`, literal `status` per exactly documented status. **Every documented body is validated strictly; a mismatch throws `ResponseValidationError` carrying the status.** That holds for successes and errors alike — an exact status (200, 401, 404, 500…), a `4XX`-style range or `default`. A body that does not match its schema (the wrong shape, a key a strict schema does not declare, a proxy's HTML page on a documented status) is a contract violation: the call rejects with a `ResponseValidationError` that has `status`, `headers`, `url`, the raw `body`, and the ZodError (or, for a non-JSON body, the JSON SyntaxError) as `cause`; its message reads `Response to GET /tasks/{taskId} (500) does not match the contract`. A status is matched exact → range → `default` (Go mode's precedence); a status none of them documents resolves `data: null` — there is nothing to validate it against. A method **never throws on an HTTP status** as such — only on a network error / abort, invalid params (before the request), or that contract violation. The return type is one `ApiResponse<T, S>` per exact status plus a catch-all `ApiResponse<Envelope, number>` per range/`default` (and `ApiResponse<null, number>` without `default`), so check `res.data` after checking `status`.
- **Headers** are layered: `options.headers` → the body's content type → the operation's header params → `requestInit.headers`, each winning over the one before. A multipart or urlencoded body always gets the content type fetch writes for it, even if a default `Content-Type` is set.
- **Encoding** matches the other TS modes: path params percent-encoded; query arrays repeat the key (comma-joined for `explode: false`), objects are sent as JSON, `undefined`/`null` are left out; multipart via `FormData`, urlencoded via `URLSearchParams`, raw binary bodies as the `Blob`/`File` you pass (`BinaryInput = Blob | File`).

### `swift` — iOS / macOS

No external dependencies (Foundation only). Add the `.swift` file to your Xcode project.

```swift
let api = ApiClient(baseURL: URL(string: "https://api.example.com")!)
let response = try await api.listTasks(page: 1, limit: 10)
```

Constructor: `init(baseURL: URL, session: URLSession = .shared)`. Schemas are `Codable` structs; failures throw an `APIError` enum.

### `kotlin` — Android / JVM

Uses Ktor + kotlinx.serialization.

```kotlin
val httpClient = HttpClient(CIO) {
    install(ContentNegotiation) { json() }
}
val api = ApiClient(client = httpClient, baseUrl = "https://api.example.com")
val response = api.listTasks(page = 1, limit = 10)
```

Constructor: `ApiClient(client: HttpClient, baseUrl: String)`. Schemas are `@Serializable` data classes; operations are `suspend` functions returning `ApiResponse<T>` and throw `ApiException` on error.

```kotlin
// build.gradle.kts
plugins { kotlin("plugin.serialization") version "2.1.0" }
dependencies {
    implementation("io.ktor:ktor-client-core:3.1.0")
    implementation("io.ktor:ktor-client-cio:3.1.0")
    implementation("io.ktor:ktor-client-content-negotiation:3.1.0")
    implementation("io.ktor:ktor-serialization-kotlinx-json:3.1.0")
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0")
}
```

### `php` — Symfony HttpClient

Composer dependencies: `symfony/http-client`, `symfony/serializer`, `symfony/property-info`, `symfony/property-access`, `phpdocumentor/reflection-docblock`.

```php
use App\Api\ApiClient;
use Symfony\Component\HttpClient\HttpClient;

$api = new ApiClient(HttpClient::create(), 'https://api.example.com');
$response = $api->listTasks(page: 1, limit: 10);
$response->data;   // typed model, hydrated via Symfony Serializer
$response->status; // 200
```

Constructor: `new ApiClient(HttpClientInterface $client, string $baseUrl, ?SerializerInterface $serializer = null)` (a sensible serializer is built by the generated `SerializerFactory` when omitted; the third parameter is dropped entirely for a spec whose operations never serialize or deserialize a typed body). Output is a PSR-4 directory — models under `Model/`, plus `ApiResponse`, `ApiException` (thrown on every non-2xx), and the client class. `--php-version` gates emitted features: backed enums + `readonly` need 8.1+, `readonly class` 8.2+, typed constants 8.3+, `#[\Deprecated]` 8.4+, `#[\NoDiscard]` + `Uri\Rfc3986` URL building 8.5. Code generated for 8.0 uses serializer `^5.4|^6.x` (`AnnotationLoader`); 8.1+ requires serializer >= 6.4.

### `php-legacy` — PHP 7.3, no Composer

For consumers stuck on an old PHP (an information system on 7.3, say) that cannot install Symfony. Requirements: `ext-curl` and `ext-json`, nothing else. Unlike the `php` mode it writes **into the output directory itself**: `README.md` plus `src/` with one class per file under `--namespace` (RobotLoader or any PSR-4 loader indexes `src/`).

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

```php
$client = new MedelySyncClient(
    new CurlTransport(),
    new ClientCredentials($clientId, $clientSecret, new FileTokenStore('/var/cache/app')),
    'https://api.example.com'
);
$doctor = $client->upsertDoctor('r-1', new Model\UpsertDoctorRequest('Jana', 'Nova')); // Model\DoctorResponse
```

- **Layout**: `<Client>.php` (one public method per operation, returning the typed model, `void` for 204, the raw string for a byte download), `Http/` (`Transport`, `CurlTransport`, `Request`, `Response`), `Auth/` (`Authenticator`, `ClientCredentials`, `TokenStore`, `MemoryTokenStore`, `FileTokenStore`), `Exception/` (`MedelyException` > `ApiException` with `getStatusCode()`/`getErrorCode()`/`getBody()`/`getResponseHeaders()`, `TransportException`, `UnexpectedResponseException`), `Multipart/FilePart`, `Internal/Support`, `Model/*`.
- **`Auth\ClientCredentials`** is generated from the spec's OAuth2 `clientCredentials` security scheme: it POSTs the form with an explicit `scope`, caches the token (in a `TokenStore`) until `expires_in` minus 60 s, and retries once on a 401. An operation with `security: []` (the token operation itself) is never authorized.
- **Models** are immutable (private untyped properties with `@var`, 7.1-style constructor hints, getters only). `fromArray()` checks the required keys and throws `UnexpectedResponseException`; `toArray()` writes only declared fields, leaving out a `null` optional. Date-times are `\DateTimeImmutable` (`DATE_ATOM`). **Enums are lenient**: the property holds the raw string and the `Model\<Enum>` class is a constants holder with `values()`/`isKnown()`, so a value the API adds later cannot crash an old client.
- **Banned in the output** (checked by a test): `fn`, `match`, `??=`, `enum`, typed properties (7.3), named arguments, `mixed` as a type, `?->`, attributes, union types. `--php-version 7.4` only switches on typed properties.
- Multipart bodies go through `CURLFile` (`FilePart::fromString()` writes a temp file, since `CURLStringFile` is 8.1+); an array field is sent as `name[0]`, `name[1]`.

### `go` — standard library `net/http`

No dependencies beyond the standard library; Go 1.27+. The output is one package directory (`client.go`, `operations.go`, `models.go`, `enums.go`, `unions.go`, `errors.go`, `runtime.go`), already gofmt-formatted.

```go
api, err := petstore.NewClient(
	petstore.WithBaseURL("https://api.example.com"),
	petstore.WithRequestEditor(func(ctx context.Context, req *http.Request) error {
		req.Header.Set("Authorization", "Bearer "+token)
		return nil
	}),
)
res, err := api.ListTasks(ctx, &petstore.ListTasksParams{Page: petstore.Ptr(1)})
res.Data       // TaskList
res.StatusCode // 200

_, err = api.GetTask(ctx, "missing")
var getErr *petstore.GetTaskError
if errors.As(err, &getErr) && getErr.Status404 != nil {
	fmt.Println(getErr.Status404.Message) // the documented 404 body, typed
}
```

Every operation is `(ctx, path params…, required query/header params…, body, *<Op>Params) (*APIResponse[T], error)`. A non-2xx response is always that operation's own `*<Op>Error`, which has one typed field per documented error status and unwraps to the shared `*APIError`. Optional fields are pointers (`Ptr` helps), enums are typed constants that reject undeclared values (or, with `--lenient-enums`, keep them — check `Valid()` — so an API that grows an enum value, as App Store Connect does, does not break every response carrying it), and `oneOf`/`anyOf` unions are structs with one pointer per branch.

## Agent skills

The package ships [agent skills](skills/) — Markdown playbooks for AI coding agents covering CLI usage (`generate-client`) and per-mode integration (`integrate-{full,playwright,backend,swift,kotlin,php,php-legacy,go}-client`, `integrate-zod-schemas`). Compatible tools discover them automatically once the package is installed.

## Development

Requires [Bun](https://bun.sh) and [Task](https://taskfile.dev/).

```bash
bun install
task test        # run the vitest suite
task lint        # oxlint
task build       # bundle src/bin.ts -> dist/bin.js
task run         # generate a sample client from fixtures/api.json into out/
```

Run a single test file: `bun vitest run src/__tests__/converter/primitives.test.ts`

See [CLAUDE.md](CLAUDE.md) for architecture details and the full task list. `task run-pw`, `task run-backend`, `task run-swift`, `task run-kotlin`, `task run-php`, `task run-php-legacy`, `task run-go`, and `task run-zod` generate sample clients for the other modes. Runtime integration tests (`task test-runtime`) require a Java/Gradle toolchain (Kotlin), a Swift toolchain (Swift), PHP >= 8.1 + Composer (PHP), Docker with the `php:7.3-cli` image (php-legacy: lint, PHPStan at `phpVersion: 70300` and a runtime smoke test against a stub server), or Go >= 1.27 (Go) and are skipped otherwise.

## License

No license has been declared for this package yet. Add a `LICENSE` file and a `license` field to `package.json` / `package.json.dist` before publishing publicly.
