openapi-typescript
TypeScript icon, indicating that this package has built-in type declarations

7.6.1 • Public • Published

openapi-typescript

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:

npm i -D openapi-typescript typescript

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

{
  "compilerOptions": {
+    "module": "ESNext", // or "NodeNext"
+    "moduleResolution": "Bundler" // or "NodeNext"
  }
}

Highly recommended

Also adding the following can boost type safety:

{
  "compilerOptions": {
+    "noUncheckedIndexedAccess": true
  }
}

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:

# Local schema
npx openapi-typescript ./path/to/my/schema.yaml -o ./path/to/my/schema.d.ts
# 🚀 ./path/to/my/schema.yaml -> ./path/to/my/schema.d.ts [7ms]

# Remote schema
npx openapi-typescript https://myapi.dev/api/v1/openapi.yaml -o ./path/to/my/schema.d.ts
# 🚀 https://myapi.dev/api/v1/openapi.yaml -> ./path/to/my/schema.d.ts [250ms]

Then in your TypeScript project, import types where needed:

import type { paths, components } from "./my-openapi-3-schema"; // generated by openapi-typescript

// Schema Obj
type MyType = components["schemas"]["MyType"];

// Path params
type EndpointParams = paths["/my/endpoint"]["parameters"];

// Response obj
type SuccessResponse =
  paths["/my/endpoint"]["get"]["responses"][200]["content"]["application/json"]["schema"];
type ErrorResponse =
  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

Versions

Current Tags

VersionDownloads (Last 7 Days)Tag
7.6.1469,402latest
5.4.259,267swagger-v2
7.0.0-rc.188next

Version History

VersionDownloads (Last 7 Days)Published
7.6.1469,402
7.6.014,837
7.5.250,555
7.5.13,585
7.5.0153
7.4.495,067
7.4.344,592
7.4.214,808
7.4.121,576
7.4.07,605
7.3.3272
7.3.2467
7.3.12
7.3.022,406
7.2.01,491
7.1.2121,286
7.1.1652
7.1.03,641
7.0.4640
7.0.3207
7.0.228,048
7.0.1691
7.0.09,156
7.0.0-rc.188
7.0.0-rc.0978
6.7.6219,323
7.0.0-next.11250
7.0.0-next.10242
7.0.0-next.91
6.7.545,294
7.0.0-next.81,679
5.4.259,267
7.0.0-next.7316
6.7.435,784
7.0.0-next.63
6.7.314,139
6.7.23,411
7.0.0-next.51,001
7.0.0-next.445
7.0.0-next.33
6.7.19,080
7.0.0-next.2545
7.0.0-next.14
7.0.0-next.04
6.7.018,009
6.6.299
6.6.2-beta.04
6.6.11,858
6.6.0272
6.5.52,279
6.5.42,389
6.5.31,449
6.5.2293
6.5.13
6.5.01,071
6.4.5714
6.4.4129
6.4.3375
6.4.2203
6.4.12
6.4.09,511
6.3.9408
6.3.84
6.3.72,583
6.3.61
6.3.589
6.3.42,287
6.3.37
6.3.2493
6.3.127
6.3.03
6.2.9152
6.2.82,273
6.2.7185
6.2.62,329
6.2.5727
6.2.44,385
6.2.3300
6.2.24
6.2.19,214
6.2.0624
6.1.1346
6.1.02,791
6.0.369
6.0.23
6.0.155
6.0.03
5.4.124,912
6.0.0-pre.044
5.4.012,811
5.3.0921
5.2.0655
5.1.1166
5.1.01,011
5.0.14
5.0.0858
4.5.010,648
4.4.0314
4.3.035
4.2.03
4.1.12
4.1.02
4.0.27,988
4.0.11,600
4.0.05
4.0.0-pre.02
3.4.18,054
3.4.01
3.4.0-pre.21
3.4.0-pre.12
3.4.0-pre.01
3.3.1763
3.3.052
3.2.431
3.3.0-next.02
3.2.3198
3.2.211
3.2.14
3.2.05,004
3.1.23
3.1.12
3.1.01
3.1.0-rc.01
3.1.0-alpha.02
3.0.41
3.0.32
3.0.22
3.0.1488
3.0.06
3.0.0-alpha.31
2.5.0160
3.0.0-alpha.21
3.0.0-alpha.12
3.0.0-alpha.02
3.0.0-rc.01
2.4.245
2.4.13
2.4.02
2.3.41
2.3.32
2.3.23
2.3.11
2.3.09
2.2.11
2.2.02

Package Sidebar

Install

npm i openapi-typescript

Weekly Downloads

1,447,467

Version

7.6.1

License

MIT

Unpacked Size

530 kB

Total Files

87

Last publish

Collaborators

  • drewpowers
  • gzm0