openapi-typescript

openapi-typescript converts OpenAPI 3.0 and 3.1 schemas (JSON or YAML, local or remote) into TypeScript type definitions in milliseconds, without running a Java process, spinning up an OpenAPI server, or generating any runtime code. It works by parsing and bundling the schema with Redocly’s OpenAPI core tooling, then building a TypeScript AST directly (rather than templating strings) so the emitted paths, components, and webhooks types are accurate, fast to generate even for huge schemas, and completely free of runtime overhead.

The project is the flagship package in the openapi-ts monorepo, which also ships openapi-fetch (a tiny, fully-typed fetch wrapper) and openapi-react-query (typed TanStack Query hooks) that consume the generated types directly. Used standalone via its CLI or programmatically via its exported openapiTS() API, it has become the de facto way JavaScript and TypeScript teams keep hand-written or generated API clients in sync with a source-of-truth OpenAPI schema.

What You Get

• A openapi-typescript CLI that reads a local or remote OpenAPI schema (JSON/YAML) and writes a single .d.ts file with paths, components, operations, and webhooks types
• A programmatic openapiTS() API returning a TypeScript AST, for teams that want to post-process or embed generation in their own build pipeline
• Support for OpenAPI 3.0 and 3.1, including advanced schema features like discriminators, oneOf/allOf/anyOf, and enums (as unions or true TS enums)
• Extensive CLI flags for controlling output shape: --immutable, --enum, --export-type, --properties-required-by-default, --additional-properties, and more
• Direct interoperability with openapi-fetch and openapi-react-query, which consume the generated types to produce fully type-checked HTTP calls and React Query hooks with zero manual typing

Common Use Cases

• Generating a typed API client layer for a frontend or backend service by pointing the CLI at an existing OpenAPI/Swagger schema
• Keeping hand-written SDKs or internal npm packages in sync with a backend’s OpenAPI spec as part of CI, using --check to fail the build on drift
• Pairing with openapi-fetch to get a fully type-safe fetch client without hand-writing request/response types
• Validating that request bodies, query params, and response shapes used throughout a codebase match the current API contract
• Generating types for third-party public APIs (GitHub, Stripe, DigitalOcean) directly from their published OpenAPI schemas

Under The Hood

Architecture - The codebase cleanly separates parsing from transformation: lib/redoc.ts wraps @redocly/openapi-core to validate and bundle the input schema (resolving $refs, merging multi-file specs), while the transform/ directory holds one module per OpenAPI object type (schema-object.ts, path-item-object.ts, parameter-object.ts, operation-object.ts, webhooks-object.ts, etc.), each responsible for turning its slice of the schema into TypeScript AST nodes. Rather than string-templating output, the generator builds real ts.Node trees via the TypeScript Compiler API and prints them with astToString, which avoids a whole class of formatting/escaping bugs common in naive codegen tools. This design scales well: the project explicitly targets huge schemas generating in milliseconds.

Tech Stack - Written entirely in TypeScript (99.9% of the codebase) and shipped as dual ESM/CJS builds via unbuild. It depends on @redocly/openapi-core for spec bundling/validation, the native typescript compiler API for AST construction and printing, change-case/scule for identifier casing, and yargs-parser for CLI argument parsing — a deliberately small, focused dependency set for a tool that runs in everyone’s build pipeline. Biome handles linting and formatting, and vite-node drives auxiliary scripts (schema downloads, example regeneration).

Code Quality - The test/ directory covers CLI behavior (cli.test.ts), the Node API (node-api.test.ts, index.test.ts), CJS interop, YAML-specific parsing, discriminator handling, and invalid-schema error paths, backed by a large fixtures/ corpus. A separate test:exports script runs @arethetypeswrong/cli (attw) against the built package to catch ESM/CJS export mismatches before publish, and test:examples type-checks every example against its generated output — a strong signal of attention to type-level correctness, not just runtime behavior.

API Design - The CLI mirrors the tool’s core job with a single positional input and an --output flag, while dozens of well-documented boolean/string flags (--enum, --immutable, --export-type, --default-non-nullable, --properties-required-by-default) let consumers tune the exact shape of emitted types without post-processing. The programmatic openapiTS() export exposes the same knobs as options, and re-exports of every transform function (transformSchemaObject, transformPathItemObject, etc.) let advanced users hook into or override individual parts of the pipeline. The tight coupling with sibling packages openapi-fetch and openapi-react-query means the generated types are designed from the start to compose with a typed runtime client, not just serve as documentation.