The Problem
Developers need a reliable way to turn an OpenAPI specification into ready‑to‑use TypeScript assets (SDKs, schemas, query hooks, etc.) without hand‑crafting boilerplate or maintaining divergent client codebases.
What This Does
openapi-ts is a code‑generator that consumes any OpenAPI document and emits TypeScript modules tailored to the chosen runtime. Core generation lives in dev/openapi-ts.config.ts, which defines the input spec and output locations. The generated SDK, schema, and utility files are placed under examples/openapi-ts-angular-common/src/client/ (e.g., client.gen.ts, schemas.gen.ts, types.gen.ts).
A rich plugin ecosystem lives in docs/openapi-ts/plugins/ and is referenced from the config file; each markdown file (e.g., plugins/axios.md, plugins/zod.md) documents a concrete plugin implementation. The repository also ships full framework examples (Angular, Vue, Next.js, etc.) under examples/, showing how the generated code integrates with real projects.
How To Use It
Clone & install – the repo is mono‑repo style; each sub‑package has its own package.json. For a quick start, work inside the Angular example:
git clone https://github.com/hey-api/openapi-ts.git cd openapi-ts/examples/openapi-ts-angular-common npm ci # installs exact lockfile versions Configure the generator – edit openapi-ts.config.ts (in the same folder) to point input at your OpenAPI JSON/YAML and set output to the src/client/ directory. The file follows the shape described in docs/openapi-ts/configuration/.md. Run the generator – the CLI is exported by the package @hey-api/openapi-ts. The example’s package.json defines a script "generate": "openapi-ts" (verified in examples/openapi-ts-angular-common/package.json). Execute:
npm run generate
The command produces the .gen.ts files under src/client/. Consume the SDK – import the generated client in your Angular app, e.g.:
import { createClient } from './client/client.gen'; const api = createClient({ baseUrl: 'https://api.example.com' }); api.getUser({ userId: '123' }).then(console.log);
Similar import patterns apply to the other framework examples.
Real‑World Use
A SaaS product that publishes an OpenAPI spec can add openapi-ts to its CI pipeline. After each spec change, npm run generate runs, producing a version‑locked TypeScript SDK that is published to an internal npm registry. Front‑end teams then import the SDK directly, guaranteeing type‑safe calls without hand‑rolled request wrappers.
Code Health & Issues
Low severity – Documentation depth – The repo contains 126 markdown files, including detailed plugin guides, but the top‑level README lacks a quick‑start snippet. New users must navigate to docs/openapi-ts/get-started.md. Medium severity – Test coverage – Only four test files are present (tests/changelog.test.ts). No unit tests target the core generator logic, which may hide edge‑case bugs. Low severity – CI configuration – GitHub Actions workflows (.github/workflows/ci.yml, coverage.yml) are defined and badge shows passing status, indicating basic CI health. Low severity – Dependency hygiene – Multiple package.json files lock dependencies via npm ci; no lockfile is present at the repository root, which could lead to version drift when working outside the example folders. Low severity – License & Legal – MIT license is present (LICENSE.md). No obvious secret keys or credentials are committed.
Overall the codebase follows a clear separation: config (dev/), documentation (docs/), and consumable examples (examples/). No glaring architectural anti‑patterns are evident.
The Bottom Line
openapi-ts delivers a practical, plugin‑driven pipeline for generating type‑safe TypeScript clients from any OpenAPI spec, with solid CI and an extensive docs set. The main drawbacks are minimal automated testing of the generator itself and a fragmented package layout that may require extra steps to set up in non‑example projects. Teams that need repeatable, typed API clients and are comfortable managing a mono‑repo will find it a strong fit; smaller projects may prefer a lighter‑weight generator with tighter test coverage.