openapi-typescript: generating TypeScript types from OpenAPI 3 specs

What openapi-typescript is for, and who should reach for it

An OpenAPI document describes paths, operations, parameters, request bodies and responses. TypeScript knows none of that. Hand-written interfaces drift from the spec the moment someone edits the YAML, and the drift is silent until a field is renamed in production. openapi-typescript exists to close that gap: it reads a static OpenAPI schema and emits TypeScript types. The README describes the package as generating "TypeScript types from static OpenAPI schemas", which is the whole scope. It is aimed at TypeScript teams that already treat an OpenAPI document as the contract and want the compiler, not a runtime validator, to catch mismatches. If your API is defined in code first and the spec is a byproduct, this tool still works, but you are generating types from an artifact nobody maintains, and that is a different problem.

Types as output: the mechanism behind openapi-typescript codegen

The repository is a pnpm monorepo. The top level holds packages/ next to docs/, and the workspace is wired through pnpm-workspace.yaml and turbo.json, with build, lint, test and format scripts delegated to Turbo. That layout matters because the tool is not one binary: the README lists openapi-typescript for generating types from static schemas, and openapi-fetch for fetching "automatically from your OpenAPI schema". The first package is the code generator; the second consumes what it produces. The data flow is one-directional and offline. You point the generator at a schema file or URL, it parses the document, and it writes a TypeScript module. There is no server, no runtime dependency in your application bundle, and no schema fetched at request time. That is the design choice worth noticing: the generated file is a build artifact you commit or regenerate in CI, so a schema change becomes a diff you review rather than a runtime surprise.

Installing openapi-typescript and generating your first types

The generator is a development dependency, not a runtime one. The README points at the packages/openapi-typescript directory for the generator and packages/openapi-fetch for the client, and the docs site at openapi-ts.dev carries the install and usage instructions. The repository itself gives the monorepo scripts rather than a published install line: the root package.json defines build as "turbo run build", dev as "pnpm run -r --parallel --filter \"{packages/*}\" --aggregate-output dev", and test as "turbo run test", with [email protected] pinned as the package manager. So the repository-level entry point is pnpm, not a single CLI invocation.

pnpm install
pnpm run build
pnpm run test

Those three commands install the workspace, build every package through Turbo, and run the test task across the workspace. What you should see is Turbo orchestrating each package's own build and test scripts in dependency order. For consuming the generator in your own project, the README directs you to the per-package guides, and the openapi-fetch package is the one the root package.json constrains: a size-limit entry caps packages/openapi-fetch/dist/index.mjs at 7.5 kB. That is the clearest published constraint on the runtime half, and it tells you the project intends the client to stay small rather than grow into a framework.

Where openapi-typescript stops short

The generator emits types. It does not emit runtime code. There is no request function, no serializer, no validator and no mock server in the output, and the README does not claim otherwise. If your team expects a generated SDK with methods you can call directly, this project is the wrong shape; you would be writing the calling layer yourself or pairing it with openapi-fetch. The second limitation is the input. The topics list openapi, openapi3 and openapi3-1, and the README says "static OpenAPI schemas". A Swagger 2.0 document is not an OpenAPI 3 document, and nothing in the documentation suggests conversion is part of the job. Third, the generated file is only as accurate as the schema. A spec with loose schemas, missing response definitions or free-form objects produces types that compile but tell you little; the tool faithfully reproduces the ambiguity. Finally, the monorepo ships several packages on separate version lines, with openapi-typescript at 7.13.0, openapi-typescript-helpers at 0.1.0 and openapi-react-query at 0.5.4 in the same release batch. If you depend on more than one, you are tracking more than one version, and the helpers package is still on a 0.x line.

openapi-typescript versus Orval and Swagger TypeScript API

The related searches around this project keep returning to comparisons, and the comparison is real. openapi-typescript generates types and leaves the client to you or to openapi-fetch. Orval and swagger-typescript-api generate a client: functions or classes per operation, with the HTTP call already written. The difference in approach is where the generated artifact sits. With openapi-typescript you get a declaration file that produces no JavaScript at build time and no runtime weight, and you keep control of how requests are made. With a client generator you get working call sites immediately, at the cost of a generated runtime layer you must regenerate and re-review whenever the schema moves. Neither is strictly better. If your application already has an HTTP layer with interceptors, retries and auth handling, adding a generated client means either duplicating that logic or fighting the generator's conventions. If you have no HTTP layer and want one fast, a client generator saves the wiring. The size-limit entry in the root package.json is the clearest signal of which side of that line this project chose.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-21, one day before this article. The most recent releases listed are [email protected], [email protected] and [email protected], all published on 2026-02-11. So the codebase moves more often than the published packages, which is normal for a monorepo where docs and CI changes also count as pushes. The project is MIT licensed, which permits commercial use and modification; the LICENSE file sits at the repository root. That is a statement about the licence text, not legal advice, and if you redistribute the generated output inside a product you should read the licence yourself. Upgrade cost is mostly the regenerated file. Because the output is a build artifact, a version bump shows up as a diff in your generated types, and the review question is whether the changed types reflect a real API change or a generator change. The root package.json wires versioning through changesets, with a version script that runs the build before changeset version, which suggests releases are deliberate rather than ad hoc. The multi-package layout is the part to watch: pinning the generator and the fetch client independently is possible, but the versions move on separate lines.

Editorial conclusion

Adopt openapi-typescript when your schema is the source of truth and you want types, not a generated HTTP client: install it as a dev dependency, run the CLI against your spec, and pair it with openapi-fetch if you need a typed caller. Skip it when you need generated runtime code, validators, or a framework-specific SDK, because the README describes type generation only. Before committing, check that your spec is OpenAPI 3 or 3.1 and not Swagger 2.0, and confirm the generated paths and operations match the endpoints you actually call.

Frequently asked questions

Official sources

1. License: MIT
2. openapi-ts/openapi-typescript on GitHub
3. Project website
4. README
5. Releases