feat: add openapi typescript client (#2885)

feat(openapi-typescript): added generate-client

Author: Marshevskyy

.changeset/client-generator.md

@@ -0,0 +1,8 @@
+---
+'@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 — auth, retries, middleware, typed SSE streaming, pagination, and multipart included — plus optional companion generators for Zod validation, TanStack Query and SWR hooks, MSW mocks, and date transformers.
+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.

.claude/skills/redocly-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: redocly-cli
-description: Redocly CLI usage for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions. Use when linting an API description, bundling or splitting multi-file descriptions, joining several APIs into one, transforming a description with decorators, building or previewing API docs, testing a live API with respect to its description.
+description: Redocly CLI usage for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions. Use when linting an API description, bundling or splitting multi-file descriptions, joining several APIs into one, transforming a description with decorators, building or previewing API docs, testing a live API with respect to its description, generating a TypeScript client from an OpenAPI description.
 ---
 
 # Redocly CLI usage
@@ -38,6 +38,7 @@ Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/c
 | `preview`                                   | Local preview of a Redocly project                                  |
 | `respect`                                   | Run API tests described in an Arazzo description against a live API |
 | `generate-arazzo`                           | Scaffold an Arazzo description from an OpenAPI description          |
+| `generate-client`                           | Generate a typed, zero-dependency TypeScript client [experimental]  |
 | `login` / `logout` / `push` / `push-status` | Authenticate and push to the Redocly platform (Reunite)             |
 
 Exit codes: `0` success, `1` problems found or execution failed, `2` configuration error.
@@ -118,6 +119,29 @@ rules:
   my-plugin/operation-id-not-test: error
 ```
 
+## Generate a TypeScript client
+
+`generate-client <api> --output client.ts` turns an OpenAPI description into a typed client — one self-contained file with zero runtime dependencies (auth, retries, middleware, typed SSE, pagination included).
+Configure it durably under a `client` block in `redocly.yaml` instead of flags:
+
+```yaml
+client:
+  generators: [sdk, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path
+  outputMode: split
+  pagination: # config-only, no CLI flag
+    style: cursor
+    cursorParam: after
+    nextCursor: /page/endCursor
+    items: /items
+apis:
+  my-api:
+    root: ./openapi/openapi.yaml
+    clientOutput: ./src/api/client.ts
+```
+
+With `apis.<name>.clientOutput` set, a bare `redocly generate-client` generates every opted-in API.
+An API's own `client` block replaces the top-level one wholesale — repeat the shared fields in it.
+
 ## Test a live API
 
 `respect` executes an [Arazzo](https://spec.openapis.org/arazzo/latest.html) description as a test suite against a running API, asserting real responses match the description.
@@ -139,6 +163,7 @@ Start from `generate-arazzo <openapi>` to scaffold the workflows, then refine th
 - `respect` currently covers only synchronous HTTP flow.
 - Any `redocly.yaml` in the working directory configures every command — a stray one changes lint results silently.
 - `--extends` on the command line sets the base ruleset for that run; useful for a quick `--extends=spec` conformance check.
+- `generate-client` needs the `typescript` package (6.x) available at generation time; the generated client itself compiles with any TypeScript, including 7.
 
 ## Resources
 

.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,10 +223,14 @@ 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 and dependencies, so npm links the local
           # workspace packages instead of installing the published versions
           jq ".version = \"$VERSION\"" packages/cli/package.json > tmp.json && mv tmp.json packages/cli/package.json
-          jq ".devDependencies[\"@redocly/openapi-core\"] = \"$VERSION\" | .devDependencies[\"@redocly/respect-core\"] = \"$VERSION\"" packages/cli/package.json > tmp.json && mv tmp.json packages/cli/package.json
+          jq ".devDependencies[\"@redocly/openapi-core\"] = \"$VERSION\" | .devDependencies[\"@redocly/respect-core\"] = \"$VERSION\" | .devDependencies[\"@redocly/client-generator\"] = \"$VERSION\"" packages/cli/package.json > tmp.json && mv tmp.json packages/cli/package.json
 
           # Add comment with installation instructions
           COMMENT="📦 A new experimental 🧪 version **v$VERSION** of Redocly CLI has been published for testing.
@@ -238,9 +247,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
 
@@ -260,3 +266,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

@@ -199,10 +199,11 @@ To test local changes as a package, you can use the following steps:
 1. (Optional) Change the version of the packages.
 
 1. Run `npm run pack:prepare` in the repository's root.
-   This command generates **redocly-cli.tgz**, **respect-core.tgz**, and **openapi-core.tgz** files.
+   This command generates **redocly-cli.tgz**, **respect-core.tgz**, **openapi-core.tgz**, and **client-generator.tgz** files.
 
 1. Copy these **.tgz** files to a destination folder and then run `npm install redocly-cli.tgz` there to install Redocly CLI.
    To install `openapi-core`: repeat this step, but with **openapi-core.tgz** file.
+   Apps that consume a `runtime: package` generated client install **client-generator.tgz** the same way.
 
 ## Tests
 
@@ -213,6 +214,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 `--generator`.
+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.