openapi ts

The Problem

Developers need a reliable way to turn an OpenAPI spec into ready‑to‑use TypeScript client code (SDKs, Zod schemas, TanStack Query hooks, etc.). Maintaining hand‑written adapters for each HTTP client quickly becomes a source of bugs and duplicated effort.

What This Does

openapi-ts is a mono‑repo that bundles a code generator and a suite of framework‑specific adapters. The generator lives in packages/ (e.g., packages/openapi-ts/src/createClient.ts) and produces files such as examples/openapi-ts-axios/src/client/sdk.gen.ts and the many *.types.gen.ts files found in each example.

• Core generation logic (createClient, makeMethodFn, makeSseFn) is exercised 135 times each, stitching together request helpers, SSE support, and configuration merging.
• The generated SDKs are framework‑agnostic; adapters for Axios, Fetch, Angular, Nuxt, Fastify, etc., live under examples/ and simply re‑export the same client shape with a thin wrapper.
• Plugins (20+) are discovered at build time and can inject extra code (e.g., Zod schema generation) without touching the core generator.

How It Is Wired

Execution starts in the example entry points:

All of them eventually call the generator core:

1. setup → createClient (in packages/openapi-ts/src/createClient.ts) – creates a client factory.
2. createClient calls makeMethodFn and makeSseFn (135 calls each) to produce per‑operation functions.
3. Each method function invokes request → parse (21 edges) to perform HTTP calls and deserialize responses.
4. Configuration is merged via mergeConfigs (16 calls) and createConfig (16 calls).

A single outbound side‑effect is the filesystem write performed by generateOutput (called from setup → createClient → generateOutput) which uses fs.writeFileSync. One generated file (examples/openapi-ts-openai/src/client/sdk.gen.ts) also triggers a model inference call (e.g., an OpenAI request) as part of its SDK logic.

The most‑central functions by call‑count are resolve (24 callers), requestOptions (20), and createQueryKey (16). Their wide usage means changes here have the highest blast radius across all generated SDKs.

No cycles of high depth appear in the resolved call graph; the flow is essentially a tree from the entry point down to request/parse and finally to the network layer.

How To Use It

# Clone the repo (exact URL required)
git clone https://github.com/moses-y/openapi-ts
cd openapi-ts

# Install dependencies (pnpm is the declared manager)
pnpm install

# Run a concrete example – e.g., the Axios demo
pnpm --filter openapi-ts-axios dev   # starts the React app (see App.tsx)

# Or generate a client from a custom spec
pnpm run generate --filter @hey-api/openapi-ts  # uses dev/openapi-ts.config.ts

Configuration lives in dev/openapi-ts.config.ts (or the sibling dev/openapi-python.config.ts for Python). The file exports a config object consumed by the generator; no secret keys are required for the basic generation step.

Running a server example (Fastify) is done via:

pnpm --filter openapi-ts-fastify dev   # starts the Fastify server (see server.ts)

If you need a different HTTP client, replace the example folder (e.g., openapi-ts-angular) and run its dev script.

Real‑World Use

A microservice team can point openapi-ts at their OpenAPI spec, generate a TypeScript SDK, and drop the resulting client/sdk.gen.ts into a Next.js front‑end. The front‑end imports the SDK, calls client.getPetById(id), and receives a fully typed response without manual request‑building code. The generated SDK can be swapped for an Axios‑based version simply by switching the example folder.

Code Health & Issues

• High – Pin third‑party GitHub Actions to commit SHA (.github/workflows/*).
• High – Push directly to default branch in contributors.yml (use PRs).
• Medium – Add least‑privilege permissions for GITHUB_TOKEN (.github/workflows/ci.yml).
• Medium – Add a dependency‑vulnerability scan to CI.
• Medium – Move large binary docs/public/assets/raw/openapi-ts-hero.png (5 MB) to Git LFS.
• Medium – Set persist-credentials: false on checkout (.github/workflows/ci.yml).
• Low – Define timeout-minutes on workflow jobs (.github/workflows/ci.yml).

All other hygiene checks pass: tests (__tests__), CI, license, lockfile, and no committed secrets.

The Bottom Line

openapi-ts delivers a production‑grade OpenAPI → TypeScript pipeline with a clear separation between the generator core and framework adapters. The codebase is well‑tested and CI‑protected, but CI configuration needs tightening (action pinning, PR‑only merges, token permissions). Teams that already use TypeScript and need auto‑generated, client‑library‑ready SDKs will find it ready to adopt; smaller projects may prefer a lighter‑weight generator until the CI hardening is applied.