feat: openapi typescript client

.changeset/client-generator.md

@@ -0,0 +1,9 @@
+---
+'@redocly/client-generator': minor
+'@redocly/openapi-core': minor
+'@redocly/cli': minor
+---
+
+Added an experimental `generate-client` command that generates a typed, zero-dependency TypeScript client from an OpenAPI description — with auth, retries, middleware, typed SSE streaming, auto-pagination, and multipart support.
+The `--generator` option emits companion modules from the same description: `zod`, `tanstack-query`, `swr`, `transformers`, and `mock`.
+See the [`generate-client` command reference](https://redocly.com/docs/cli/commands/generate-client) and the [Use the generated client](https://redocly.com/docs/cli/guides/use-generated-client) guide.

.github/workflows/release.yaml

@@ -206,6 +206,11 @@ jobs:
           cache: npm
           registry-url: https://registry.npmjs.org
 
+      # Install before the version bump: npm links workspace packages only while
+      # their versions still match the dependency specs in package.json files.
+      - name: Install dependencies
+        run: npm install
+
       - name: Update package versions
         run: |
           TIMESTAMP=$(date +%s)
@@ -218,6 +223,10 @@ jobs:
           jq ".version = \"$VERSION\"" packages/respect-core/package.json > tmp.json && mv tmp.json packages/respect-core/package.json
           jq ".dependencies[\"@redocly/openapi-core\"] = \"$VERSION\"" packages/respect-core/package.json > tmp.json && mv tmp.json packages/respect-core/package.json
 
+          # Update Client Generator package version and dependencies
+          jq ".version = \"$VERSION\"" packages/client-generator/package.json > tmp.json && mv tmp.json packages/client-generator/package.json
+          jq ".dependencies[\"@redocly/openapi-core\"] = \"$VERSION\"" packages/client-generator/package.json > tmp.json && mv tmp.json packages/client-generator/package.json
+
           # Update CLI package version
           jq ".version = \"$VERSION\"" packages/cli/package.json > tmp.json && mv tmp.json packages/cli/package.json
 
@@ -236,9 +245,6 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.pull_request.number }}
 
-      - name: Install dependencies
-        run: npm install
-
       - name: Build packages
         run: npm run compile
 
@@ -258,3 +264,7 @@ jobs:
           npm run prepare:publish-dir
           npm publish ./.publish --tag snapshot
           npm run clean:publish-dir
+          sleep 10
+
+          cd ../client-generator
+          npm publish --tag snapshot

.github/workflows/tests.yaml

@@ -7,6 +7,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 env:
   CI: true
   REDOCLY_TELEMETRY: off
@@ -32,8 +35,44 @@ jobs:
         continue-on-error: true # Do not fail if there is an error during reporting
         uses: davelosert/vitest-coverage-report-action@d63aa97db4c0319f304f1787689de1ca548365cf # v2.11.1
 
-      - name: E2E Tests
-        run: npm run e2e
+  e2e:
+    # The e2e suite is split across shards so no single runner carries the whole set.
+    # Running all suites in one step was cancelled mid-run by the Actions service once the
+    # generate-client suites grew past ~28 (a healthy runner, no resource exhaustion);
+    # each shard stays well under that.
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: E2E Tests (shard ${{ matrix.shard }}/2)
+        run: npm run e2e -- --shard=${{ matrix.shard }}/2
+
+  examples:
+    # The examples gitignore their generated clients (only zero-install-quickstart commits
+    # its canonical copy), so this job regenerates every client and type-checks the
+    # hand-written consumer code against it.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+        with:
+          node-version: 24
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Regenerate example clients
+        run: npm run examples:regen -w @redocly/client-generator
+      - name: Type-check examples
+        run: npm run typecheck:examples -w @redocly/client-generator
 
   code-style-check:
     runs-on: ubuntu-latest

.oxfmtrc.json

@@ -10,8 +10,11 @@
     "packages/respect-core/src/modules/runtime-expressions/abnf-parser.js",
     "packages/core/src/rules/common/__tests__/fixtures/invalid-yaml.yaml",
     "tests/performance/api-definitions/",
+    "tests/e2e/generate-client/examples/*/src/api/",
+    "tests/e2e/generate-client/*-consumer/api*.ts",
     "tests/smoke/**/*.yaml",
     "snapshot*.txt",
+    "tests/e2e/generate-client/*.snapshot.ts",
     "*.html",
     "*.hbs",
     "*.toml",

.oxlintrc.json

@@ -9,7 +9,15 @@
     "builtin": true,
     "es2026": true
   },
-  "ignorePatterns": ["packages/*/lib/**", "*.js", "*.cjs"],
+  "ignorePatterns": [
+    "packages/*/lib/**",
+    "*.js",
+    "*.cjs",
+    "tests/e2e/generate-client/examples/*/src/api/**",
+    "tests/e2e/generate-client/examples/*/generate.ts",
+    "tests/e2e/generate-client/*.snapshot.ts",
+    "tests/e2e/generate-client/*-consumer/api.ts"
+  ],
   "rules": {
     "eslint/no-array-constructor": "error",
     "eslint/no-case-declarations": "error",
@@ -68,6 +76,15 @@
       "rules": {
         "eslint/no-console": "allow"
       }
+    },
+    {
+      "files": [
+        "tests/e2e/generate-client/examples/*/src/**",
+        "tests/e2e/generate-client/examples/*/worker.ts"
+      ],
+      "rules": {
+        "eslint/no-console": "allow"
+      }
     }
   ]
 }

CONTRIBUTING.md

@@ -212,6 +212,7 @@ Run `npm test` to start both unit and e2e tests (and additionally typecheck the
 ### Unit tests
 
 Run unit tests with this command: `npm run unit`.
+This command runs the suite for every package whose tests match the discovery glob — there is no per-package `npm test` script.
 
 Unit tests in the **cli** package are sensitive to top-level configuration file (**redocly.yaml**).
 

README.md

@@ -139,6 +139,21 @@ Respect is Redocly's community-edition product. Looking for something more? We a
 
 Learn more about [Respect](https://redocly.com/respect) and [get started with API contract testing](https://redocly.com/docs/respect/get-started).
 
+### Generate a TypeScript client
+
+> ⚠️ **Experimental** — flags, output, and configuration may change in any minor release until declared stable.
+
+Turn an OpenAPI description (3.0/3.1/3.2 or Swagger 2.0) into a typed TypeScript client with the `generate-client` command.
+The emitted client has zero runtime dependencies and runs in browsers, Node, Bun, Deno, and edge runtimes.
+
+```sh
+redocly generate-client openapi.yaml --output src/client.ts
+```
+
+Inline types plus a typed client instance and one async function per operation, with auth, opt-in abort-aware retries, middleware, and typed Server-Sent Events.
+The same command can also emit Zod schemas, TanStack Query / SWR hooks, MSW mocks, and more via `--generators`.
+For detailed information, read the [ `generate-client` docs](./docs/@v2/commands/generate-client.md).
+
 ### Transform an OpenAPI description
 
 If your OpenAPI description isn't everything you hoped it would be, enhance it with the Redocly [decorators](https://redocly.com/docs/cli/decorators) feature.

docs/@v2/commands/generate-client.md

@@ -0,0 +1,118 @@
+---
+slug:
+  - /docs/cli/commands/generate-client
+---
+
+# `generate-client`
+
+{% admonition type="warning" name="Experimental" %}
+`generate-client` is **experimental**: its flags, generated output, configuration schema, and custom-generator API may change in any minor release until it's stable.
+We'd love your feedback while we stabilize it.
+{% /admonition %}
+
+Generate a typed TypeScript client from an OpenAPI 3.x description.
+Swagger 2.0 descriptions are also accepted — normalized to the 3.x shape before generation.
+
+The generated client has **zero runtime dependencies** by default — it uses only web-standard APIs (`fetch`, `AbortController`, `URLSearchParams`, …), so it runs in browsers, Node, Bun, Deno, and edge runtimes.
+By default it emits a single self-contained file with inline types and one async function per operation; opt in to a versioned, npm-updatable runtime instead with [`--runtime package`](#runtime-distribution).
+
+This page covers running the command; for the generated client's runtime API (auth, error handling, middleware, retries, and the add-on generators) see [Use the generated client](../guides/use-generated-client.md).
+
+## Usage
+
+```sh
+redocly generate-client                          # every api with a `client` block or `clientOutput`
+redocly generate-client cafe                     # a single `apis:` alias from redocly.yaml
+redocly generate-client openapi.yaml -o dist/client.ts   # a file path or URL
+```
+
+With no argument, a client is generated for every api that declares a `client` block or a `clientOutput` under `apis:` (see [`client` configuration](../configuration/reference/client.md)).
+Otherwise `<api>` is a file path, a URL, or an [`apis:` alias](../configuration/index.md), resolved the same way as in other commands such as `bundle` and `lint`: an alias — or a path matching an api's `root` — uses that api's `client` block and `clientOutput`, while an unmatched path/URL uses the top-level `client` defaults.
+
+## Options
+
+| Option              | Type       | Description                                                                                                                                                                                                                       |
+| ------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `api`               | `string`   | OpenAPI description file path, URL, or an `apis:` alias. Omit it to generate for every api that has a `client` block or `clientOutput`.                                                                                           |
+| `--output`, `-o`    | `string`   | Output path (must end in `.ts`); the entry file in multi-file modes. Defaults to the api's `clientOutput`, else `<name>.client.ts` in the config dir. Not allowed when generating for multiple apis.                              |
+| `--output-mode`     | `string`   | File layout: `single` (default) or `split`. See [Output modes](#output-modes).                                                                                                                                                    |
+| `--runtime`         | `string`   | `inline` (default, self-contained file — zero runtime dependencies) or `package` (imports the runtime from `@redocly/client-generator`; engine fixes arrive via `npm update`). See [Runtime distribution](#runtime-distribution). |
+| `--generator`       | `string[]` | Generator to run — a built-in name or a custom generator's path/package; repeat the flag to run several (default `sdk`). See [Generators](../guides/use-generated-client.md#generators).                                          |
+| `--args-style`      | `string`   | Operation inputs: `flat` (default, positional) or `grouped` (a single `vars` object). See [Argument style](../guides/use-generated-client.md#argument-style).                                                                     |
+| `--enum-style`      | `string`   | Named string enums: `const-object` (default, `as const` object + union) or `union` (union only).                                                                                                                                  |
+| `--error-mode`      | `string`   | `throw` (default, throws `ApiError`) or `result` (returns `{ data, error, response }`). See [Error handling](../guides/use-generated-client.md#error-handling).                                                                   |
+| `--date-type`       | `string`   | `date`/`date-time` fields as `string` (default) or `Date` (pair with the `transformers` generator).                                                                                                                               |
+| `--query-framework` | `string`   | TanStack Query adapter: `react` (default), `vue`, `svelte`, or `solid`.                                                                                                                                                           |
+| `--mock-data`       | `string`   | `mock` generator data: `baked` (default, deterministic literals) or `faker` (`@faker-js/faker` calls).                                                                                                                            |
+| `--mock-seed`       | `number`   | Seed for `faker`-mode mocks, for reproducible data. Ignored in `baked` mode.                                                                                                                                                      |
+| `--server-url`      | `string`   | Override the server URL inlined into the runtime. Defaults to `servers[0].url`. Accepts absolute (`https://api.example.com`) or relative (`/v1`).                                                                                 |
+| `--setup`           | `string`   | Path to a publisher setup module baked into the client. See [Publisher defaults](../guides/use-generated-client.md#publisher-defaults).                                                                                           |
+| `--config`          | `string`   | Path to the `redocly.yaml` (the `client` config and `apis:` live there). Defaults to the one in the working directory.                                                                                                            |
+
+## Configuration
+
+Instead of passing flags every time, keep the settings in `redocly.yaml` under a top-level `client` block and per-API `apis.<name>.client` / `clientOutput`.
+CLI flags take precedence over the configuration.
+A per-API `client` block overrides the top-level `client` field by field; unspecified fields fall back to the top-level defaults.
+See [`client` configuration](../configuration/reference/client.md) for the full reference.
+
+Auto-pagination has **no CLI flag**: it's declared as structured configuration — [`client.pagination`](../configuration/reference/client.md#pagination) in `redocly.yaml`, or the equivalent `x-pagination` operation extension in the spec — and paginated operations gain typed `.pages()`/`.items()` async iterators.
+See [Pagination in the usage guide](../guides/use-generated-client.md#pagination).
+
+## Output modes
+
+`--output-mode` controls how the client is split across files:
+
+- `single` (default) — one file (self-contained with the default `inline` runtime).
+- `split` — two files: the schema types and type guards move to a sibling `<name>.schemas.ts`, and the entry file (everything else) re-exports them — so your imports are the same as in `single`.
+
+`--output` names the entry file; the `.schemas.ts` sibling derives from its name and directory. Both modes work with both [runtimes](#runtime-distribution).
+
+## Runtime distribution
+
+`--runtime` controls where the client's engine (request building, auth, retries, middleware, SSE) lives:
+
+- `inline` (default) — the same runtime source is embedded in the generated output (only the parts your API needs): self-contained, zero runtime dependencies.
+- `package` — the generated file imports the runtime from `@redocly/client-generator` and contains only the types, pure-data operation descriptors, and thin call wrappers:
+
+  ```ts
+  import {
+    createClient,
+    type OperationDescriptor,
+    type RequestOptions,
+  } from '@redocly/client-generator';
+
+  export const OPERATIONS = {
+    getOrderById: {
+      id: 'getOrderById',
+      method: 'GET',
+      path: '/orders/{orderId}',
+      tags: ['Orders'],
+      params: [
+        /* … */
+      ],
+    },
+    // …
+  } as const satisfies Record<string, OperationDescriptor>;
+
+  export const client = createClient<Ops>(OPERATIONS, { serverUrl: 'https://api.example.com' });
+  export const { configure, use } = client;
+  export const getOrderById = (orderId: string, init: RequestOptions = {}) =>
+    client.getOrderById({ orderId }, init);
+  ```
+
+Choose `package` when you want engine fixes and improvements to arrive via `npm update @redocly/client-generator` — no regeneration, no diff in the generated file.
+The trade: the consuming app must have `@redocly/client-generator` installed as a regular dependency.
+Your application code is identical in both modes (same exports, same call shapes).
+
+The `satisfies Record<string, OperationDescriptor>` line doubles as a **build-time version-skew guard**: an incompatible generated-file/runtime pair fails the consumer's `tsc` instead of misbehaving at runtime.
+
+In both modes the generated module exports **both call styles** — the `client` instance (grouped-args methods) and the free-function operations (`--args-style` shapes those).
+Both runtimes work with both [output modes](#output-modes) and every generator.
+
+## Resources
+
+- [Use the generated client](../guides/use-generated-client.md) — the runtime API and the add-on generators.
+- [`client` configuration](../configuration/reference/client.md) — the `redocly.yaml` `client` block.
+- [Lint command](./lint.md) to validate your API description before generating a client.
+- [Bundle command](./bundle.md) to combine a multi-file description into a single input file.

docs/@v2/commands/index.md

@@ -14,6 +14,7 @@ Documentation commands:
 API management commands:
 
 - [`bundle`](bundle.md) Bundle API description.
+- [`generate-client`](generate-client.md) Generate a typed TypeScript client from an OpenAPI description [experimental feature].
 - [`join`](join.md) Join API descriptions [experimental feature].
 - [`score`](score.md) Score an API for integration simplicity and AI agent readiness.
 - [`split`](split.md) Split API description into a multi-file structure.

docs/@v2/configuration/reference/apis.md

@@ -58,6 +58,18 @@ If your project contains multiple APIs, the `apis` configuration section allows
 - Output file path
 - When running `bundle` without specifying an API, the bundled API description is saved to this location.
 
+---
+
+- client
+- [Client object](./client.md)
+- Additional TypeScript client generation configuration for this API, used by the experimental `generate-client` command.
+
+---
+
+- clientOutput
+- Output file path
+- When running `generate-client` without specifying an API, the generated TypeScript client is saved to this location.
+
 {% /table %}
 
 ## Examples