@mzronek/openapi-typescript
v7.0.0-next.11
Published
Convert OpenAPI 3.0 & 3.1 schemas to TypeScript
Downloads
3
Maintainers
Readme
openapi-typescript generates TypeScript types from static OpenAPI schemas quickly using only Node.js. It is fast, lightweight, (almost) dependency-free, and no Java/node-gyp/running OpenAPI servers necessary.
The code is MIT-licensed and free for use.
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
- ✅ Native Node.js code is fast and generates types within milliseconds
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
✨ Tip
Enabling noUncheckedIndexedAccess in
tsconfig.json
can go along way to improve type safety (read more)
Basic usage
First, generate a local type file by running npx openapi-typescript
:
# 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]
⚠️ Be sure to validate your schemas! openapi-typescript will err on invalid schemas.
Then, import schemas from the generated file like so:
import type { paths, components } from "./api/v1"; // 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"];
🦠 Globbing local schemas
npx openapi-typescript "specs/**/*.yaml" --output schemas/
# 🚀 specs/one.yaml -> schemas/specs/one.ts [7ms]
# 🚀 specs/two.yaml -> schemas/specs/two.ts [7ms]
# 🚀 specs/three.yaml -> schemas/specs/three.ts [7ms]
Thanks, @sharmarajdaksh!
☁️ Remote schemas
npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml --output petstore.d.ts
# 🚀 https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [250ms]
Thanks, @psmyrdek!