openapi-typescript: TypeScript Types from OpenAPI

openapi-typescript reads an OpenAPI 3.x document and emits a single TypeScript definitions file describing its paths, components, and operations.

openapi-typescript generates zero-runtime types (a .d.ts-style output) consumed by typed fetch clients. It is a lightweight alternative to full SDK generators for TypeScript projects.

What it does

The CLI reads an OpenAPI file or URL and writes TypeScript type definitions for paths, components, operations, and webhooks. The output is types only, so it adds no runtime code, and pairs with a typed client like openapi-fetch.

Common usage

Terminal

npx openapi-typescript openapi.yaml -o src/api/schema.d.ts
# from a live URL
npx openapi-typescript https://api.example.com/openapi.json \
  -o src/api/schema.d.ts

Options

Flag	What it does
-o, --output <file>	Output .ts file (stdout if omitted)
--root-types	Emit root-level type aliases for schemas
--enum	Generate real TS enums instead of string unions
--alphabetize	Sort types alphabetically for stable diffs
--additional-properties	Allow extra properties on objects by default
--empty-objects-unknown	Type schemaless objects as unknown, not any

In CI

Add --alphabetize so output ordering is stable, then run the generator and git diff --exit-code on the output file so a spec change without a regen fails the PR. Generating from a checked-in spec (not a live URL) keeps CI hermetic and reproducible.

Common errors in CI

"Could not find a valid OpenAPI schema" means the input is not a 3.x document (2.0/Swagger is not supported; convert first). "Unsupported schema format" or SyntaxError means invalid YAML/JSON. A fetch error like request to https://... failed, reason: getaddrinfo ENOTFOUND means a remote spec URL is unreachable from the runner; use a local file instead.