openapi-typescript

Convert OpenAPI 3.0 & 3.1 schemas to TypeScript

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
openapi-typescript
4,421766.7.516 days ago3 years agoMinified + gzip package size for openapi-typescript in KB

Readme

openapi-typescript
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

šŸ‘€ 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

āœØ 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 { paths, components } from "./path/to/my/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"];

šŸ¦  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!

šŸ““ Docs

View Docs