openapi-typescript turns OpenAPI 3.0 & 3.1 schemas into TypeScript quickly using Node.js. No Java/node-gyp/running OpenAPI servers necessary.

The code is MIT-licensed and free for use.

Tip: New to OpenAPI? Speakeasy’s Intro to OpenAPI is an accessible guide to newcomers that explains the “why” and “how” of OpenAPI.

Features

• ✅ Supports OpenAPI 3.0 and 3.1 (including advanced features like discriminators)
• ✅ Generate runtime-free types that outperform old school codegen
• ✅ Load schemas from YAML or JSON, locally or remotely
• ✅ Generate types for even huge schemas within milliseconds

Note: OpenAPI 2.x is supported with versions 5.x and previous

Examples

👀 See examples

Setup

This library requires the latest version of Node.js installed (20.x or higher recommended). With that present, run the following in your project:

1npm i -D openapi-typescript typescript

And in your tsconfig.json, to load the types properly:

1{
2  "compilerOptions": {
3+    "module": "ESNext", // or "NodeNext"
4+    "moduleResolution": "Bundler" // or "NodeNext"
5  }
6}

Highly recommended

Also adding the following can boost type safety:

1{
2  "compilerOptions": {
3+    "noUncheckedIndexedAccess": true
4  }
5}

Basic usage

First, generate a local type file by running npx openapi-typescript, first specifying your input schema (JSON or YAML), and where you’d like the --output (-o) to be saved:

1# Local schema
2npx openapi-typescript ./path/to/my/schema.yaml -o ./path/to/my/schema.d.ts
3# 🚀 ./path/to/my/schema.yaml -> ./path/to/my/schema.d.ts [7ms]
4
5# Remote schema
6npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/schema.d.ts
7# 🚀 https://myapi.dev/api/v1/openapi.yaml -> ./path/to/my/schema.d.ts [250ms]

Then in your TypeScript project, import types where needed:

1import type { paths, components } from "./my-openapi-3-schema"; // generated by openapi-typescript
2
3// Schema Obj
4type MyType = components["schemas"]["MyType"];
5
6// Path params
7type EndpointParams = paths["/my/endpoint"]["parameters"];
8
9// Response obj
10type SuccessResponse =
11  paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
12type ErrorResponse =
13  paths["/my/endpoint"]["get"]["responses"][500]["content"]["application/json"]["schema"];

From here, you can use these types for any of the following (but not limited to):

• Using an OpenAPI-supported fetch client (like openapi-fetch)
• Asserting types for other API requestBodies and responses
• Building core business logic based on API types
• Validating mock test data is up-to-date with the current schema
• Packaging API types into any npm packages you publish (such as client SDKs, etc.)

📓 Docs

View Docs