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,112 @@
+# `generate-client`
+
+{% admonition type="warning" name="Experimental" %}
+`generate-client` is an experimental feature: 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 %}
+
+## Introduction
+
+The `generate-client` command generates a typed TypeScript client from an OpenAPI 3.x description.
+Swagger 2.0 descriptions are also accepted and normalized to the 3.x shape before generation.
+The description is validated first: unresolved `$ref`s or structural errors fail generation with the problems listed, independent of your lint configuration.
+
+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.
+
+The `<api>` argument 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`; an unmatched path or URL uses the top-level `client` defaults.
+With no argument, a client is generated for every api that declares a `client` block or a `clientOutput` (see [`client` configuration](../configuration/reference/client.md)).
+
+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
+
+```bash
+redocly generate-client
+redocly generate-client <api>
+redocly generate-client <api> [--output=<path>] [--output-mode=<mode>] [--runtime=<mode>]
+redocly generate-client <api> [--generator=<name>] [--args-style=<style>] [--error-mode=<mode>]
+redocly generate-client <api> [--config=<path>]
+```
+
+## 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` next to the configuration file. Single-API invocations only.                                                                                                                                                                |
+| `--output-mode`  | `string`   | File layout. See [Choose an output mode](#choose-an-output-mode). <br/> **Possible values:** `single`, `split`. Default value is `single`.                                                                                                                                                                                                                     |
+| `--runtime`      | `string`   | Where the client's engine lives. See [Choose a runtime](#choose-a-runtime). <br/> **Possible values:** `inline`, `package`. Default value is `inline`.                                                                                                                                                                                                         |
+| `--import-ext`   | `string`   | Extension in generated relative imports. See [Run with Node directly](../guides/use-generated-client.md#run-with-node-directly). <br/> **Possible values:** `js` (the tsc/bundler convention), `ts` (for Node's built-in type stripping). Default value is `js`.                                                                                               |
+| `--generator`    | `[string]` | Generator to run — a built-in name (`tanstack-query` also has `-vue`/`-svelte`/`-solid` variants) or a custom generator's path or package; repeat the flag to run several. Default value is `sdk`. See [Generators](../guides/use-generated-client.md#generators).                                                                                             |
+| `--args-style`   | `string`   | How operation inputs are passed. See [Argument style](../guides/use-generated-client.md#argument-style). <br/> **Possible values:** `flat`, `grouped`. Default value is `flat`.                                                                                                                                                                                |
+| `--error-mode`   | `string`   | How operations report HTTP errors. See [Error handling](../guides/use-generated-client.md#error-handling). <br/> **Possible values:** `throw`, `result`. Default value is `throw`.                                                                                                                                                                             |
+| `--date-type`    | `string`   | Type of `date`/`date-time` fields; pair `Date` with the `transformers` generator. <br/> **Possible values:** `string`, `Date`. Default value is `string`.                                                                                                                                                                                                      |
+| `--mock-data`    | `string`   | Data mode for the `mock` generator. <br/> **Possible values:** `static` (deterministic literals), `faker` (`@faker-js/faker` calls). Default value is `static`.                                                                                                                                                                                                |
+| `--mock-seed`    | `number`   | Seed for `faker`-mode mocks, for reproducible data. Ignored in `static` mode.                                                                                                                                                                                                                                                                                  |
+| `--server-url`   | `string`   | Override the server URL baked into the client. Accepts an absolute (`https://api.example.com`) or relative (`/v1`) URL. Defaults to `servers[0].url`. The app can also repoint the client at runtime — `createClient({ serverUrl })` or `configure({ serverUrl })`, see [Authentication](../guides/use-generated-client.md#authentication) in the usage guide. |
+| `--setup`        | `string`   | Path to a publisher setup module baked into the client. See [Publisher defaults](../guides/use-generated-client.md#publisher-defaults).                                                                                                                                                                                                                        |
+| `--config`       | `string`   | Specify path to the [configuration file](#generate-from-the-configuration-file).                                                                                                                                                                                                                                                                               |
+
+## Examples
+
+### Generate from the configuration file
+
+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` — see the [`client` configuration reference](../configuration/reference/client.md) for the fields and how they layer.
+CLI flags take precedence over the configuration.
+Auto-pagination has no CLI flag; it's declared only as [`client.pagination`](../configuration/reference/client.md#pagination-object) configuration or the `x-pagination` operation extension.
+
+```yaml
+client:
+  generators:
+    - sdk
+apis:
+  cafe:
+    root: ./openapi.yaml
+    clientOutput: ./src/api/client.ts
+```
+
+```bash
+redocly generate-client            # every api with a `client` block or `clientOutput`
+redocly generate-client cafe       # just the `cafe` api
+```
+
+### Generate from a file path or URL
+
+An unmatched path or URL uses the top-level `client` defaults; `--output` names the entry file:
+
+```bash
+redocly generate-client openapi.yaml --output dist/client.ts
+```
+
+### Choose an output mode
+
+`--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 re-exports them, so your imports are the same as in `single`.
+
+```bash
+redocly generate-client openapi.yaml -o src/api/client.ts --output-mode split
+```
+
+Both modes work with both runtimes.
+
+### Choose a runtime
+
+`--runtime` controls where the client's engine (request building, auth, retries, middleware, SSE) lives:
+
+- `inline` (default) — the 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, operation descriptors, and thin call wrappers.
+
+Choose `package` when you want engine fixes to arrive via `npm update @redocly/client-generator` with no regeneration; the consuming app must then have that package installed as a regular dependency.
+Your application code is identical in both modes.
+See [Package runtime](../guides/use-generated-client.md#package-runtime) in the usage guide and the [`package-runtime` example](https://github.com/Redocly/redocly-cli/tree/main/tests/e2e/generate-client/examples/package-runtime).
+
+## 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