Skip to content

Generate TypeScript types from OpenAPI 3 specs

License

Notifications You must be signed in to change notification settings

eq-fm/openapi-typescript

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

version(scoped) npm downloads (weekly) codecov

All Contributors

πŸ“˜οΈ openapi-typescript

πŸš€ Convert static OpenAPI schemas to TypeScript types quickly using pure Node.js. Fast, lightweight, (almost) dependency-free, and no Java/node-gyp/running OpenAPI servers necessary.

Features

  • βœ… Supports YAML and JSON formats
  • βœ… Supports advanced OpenAPI 3.1 features like discriminators
  • βœ… Supports loading via remote URL (simple authentication supported with the --auth flag)
  • βœ… Supports remote references: $ref: "external.yaml#components/schemas/User"
  • βœ… Fetches remote schemas quickly using undici

Examples

πŸ‘€ See examples

Usage

Note:️ openapiTS requires VALID OpenAPI 3.x schemas to work, and this library does not handle validation. There are several quality tools that handle this like @apidevtools/swagger-parser. Make sure to validate your schemas first!

πŸ–₯️ CLI

πŸ—„οΈ Reading a local schema

npx openapi-typescript schema.yaml --output schema.ts

# πŸ”­ Loading spec from schema.yaml…
# πŸš€ schema.yaml -> schema.ts [250ms]
🦠 Globbing local schemas
npx openapi-typescript "specs/**/*.yaml" --output schemas/

# πŸ”­ Loading spec from specs/one.yaml…
# πŸ”­ Loading spec from specs/two.yaml…
# πŸ”­ Loading spec from specs/three.yaml…
# πŸš€ specs/one.yaml -> schemas/specs/one.ts [250ms]
# πŸš€ specs/two.yaml -> schemas/specs/two.ts [250ms]
# πŸš€ specs/three.yaml -> schemas/specs/three.ts [250ms]

Thanks, @sharmarajdaksh!

☁️ Reading remote schemas

npx openapi-typescript https://petstore3.swagger.io/api/v3/openapi.yaml --output petstore.d.ts

# πŸ”­ Loading spec from https://petstore3.swagger.io/api/v3/openapi.yaml…
# πŸš€ https://petstore3.swagger.io/api/v3/openapi.yaml -> petstore.d.ts [650ms]

Thanks, @psmyrdek!

🟦 Using in TypeScript

Import any top-level item from the generated spec to use it. It works best if you also alias types to save on typing:

import { components } from "./generated-schema.ts";

type APIResponse = components["schemas"]["APIResponse"];

Because OpenAPI schemas may have invalid TypeScript characters as names, the square brackets are a safe way to access every property.

πŸ—οΈ Operations

Operations can be imported directly by their operationId:

import { operations } from "./generated-schema.ts";

type getUsersById = operations["getUsersById"];

Thanks, @gr2m!

⚾ Fetching data

Fetching data can be done simply and safely using an automatically-typed fetch wrapper:

Example (openapi-fetch)

import createClient from "openapi-fetch";
import { paths } from "./v1"; // (generated from openapi-typescript)

const { get, post, put, patch, del } = createClient<paths>({
  baseUrl: "https://myserver.com/api/v1/",
  headers: {
    Authorization: `Bearer ${import.meta.env.VITE_AUTH_TOKEN}`,
  },
});

See each project’s respective pages for usage & install instructions.

✨ Tip: Automatically-typed fetch wrappers are better to use than manually-assigned generics. The latter is not only more work, but it can be error-prone (which makes your OpenAPI typing worthless if it can’t catch all your errors!).

πŸ“– Options

The following flags can be appended to the CLI command.

Option Alias Default Description
--help Display inline help message and exit
--version Display this library’s version and exit
--output [location] -o (stdout) Where should the output file be saved?
--auth [token] Provide an auth token to be passed along in the request (only if accessing a private schema)
--header -x Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern
--headers-object="{…}" -h Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over --header
--http-method -m GET Provide the HTTP Verb/Method for fetching a schema from a remote URL
--immutable-types false Generates immutable types (readonly properties and readonly array)
--additional-properties false Allow arbitrary properties for all schema objects without additionalProperties: false
--empty-objects-unknown false Allow arbitrary properties for schema objects with no specified properties, and no specified additionalProperties
--default-non-nullable false Treat schema objects with default values as non-nullable
--export-type -t false Export type instead of interface
--path-params-as-types false Allow dynamic string lookups on the paths object
--support-array-length false Generate tuples using array minItems / maxItems
--alphabetize false Sort types alphabetically

🚩 --path-params-as-types

By default, your URLs are preserved exactly as-written in your schema:

export interface paths {
  "/user/{user_id}": components["schemas"]["User"];
}

Which means your type lookups also have to match the exact URL:

import { paths } from "./my-schema";

const url = `/user/${id}`;
type UserResponses = paths["/user/{user_id}"]["responses"];

But when --path-params-as-types is enabled, you can take advantage of dynamic lookups like so:

import { paths } from "./my-schema";

const url = `/user/${id}`;
type UserResponses = paths[url]["responses"]; // automatically matches `paths['/user/{user_id}']`

Though this is a contrived example, you could use this feature to automatically infer typing based on the URL in a fetch client or in some other useful place in your application.

Thanks, @Powell-v2!

🚩 --support-array-length

This option is useful for generating tuples if an array type specifies minItems or maxItems.

For example, given the following schema:

components:
  schemas:
    TupleType
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 2

Enabling --support-array-length would change the typing like so:

  export interface components {
    schemas: {
-     TupleType: string[];
+     TupleType: [string] | [string, string];
    };
  }

This results in more explicit typechecking of array lengths.

Note: this has a reasonable limit, so for example maxItems: 100 would simply flatten back down to string[];

Thanks, @kgtkr!

🐒 Node

npm i --save-dev openapi-typescript
import fs from "node:fs";
import openapiTS from "openapi-typescript";

// example 1: load [object] as schema (JSON only)
const schema = await fs.promises.readFile("spec.json", "utf8"); // must be OpenAPI JSON
const output = await openapiTS(JSON.parse(schema));

// example 2: load [string] as local file (YAML or JSON; released in v4.0)
const localPath = new URL("./spec.yaml", import.meta.url); // may be YAML or JSON format
const output = await openapiTS(localPath);

// example 3: load [string] as remote URL (YAML or JSON; released in v4.0)
const output = await openapiTS("https://myurl.com/v1/openapi.yaml");

The Node API may be useful if dealing with dynamically-created schemas, or you’re using within context of a larger application. Pass in either a JSON-friendly object to load a schema from memory, or a string to load a schema from a local file or remote URL (it will load the file quickly using built-in Node methods). Note that a YAML string isn’t supported in the Node.js API; either use the CLI or convert to JSON using js-yaml first.

πŸ“– Node options

The Node API supports all the CLI flags above in camelCase format, plus the following additional options:

Name Type Default Description
commentHeader string Override the default β€œThis file was auto-generated …” file heading
inject string Inject arbitrary TypeScript types into the start of the file
transform Function Override the default Schema Object ➝ TypeScript transformer in certain scenarios
postTransform Function Same as transform but runs after the TypeScript transformation

πŸ€– transform / postTransform

If using the Node.js API, you can override the normal Schema Object transformer with your own. This is useful for providing enhanced functionality for specific parts of your schema.

For example, say your schema has the following property:

properties:
  updated_at:
    type: string
    format: date-time

By default, openapiTS will generate updated_at?: string; because it’s not sure which format you want by "date-time" (formats are nonstandard and can be whatever you’d like). But we can enhance this by providing our own custom formatter, like so:

const types = openapiTS(mySchema, {
  transform(schemaObject, metadata): string {
    if ("format" in schemaObject && schemaObject.format === "date-time") {
      return schemaObject.nullable ? "Date | null" : "Date";
    }
  },
});

That would result in the following change:

-  updated_at?: string;
+  updated_at?: Date;

Any Schema Object present in your schema will be run through this formatter (even remote ones!). Also be sure to check the metadata parameter for additional context that may be helpful.

There are many other uses for this besides checking format. Because this must return a string you can produce any arbitrary TypeScript code you’d like (even your own custom types).

✨ Don’t forget about postTransform() as well! It works the same way, but runs after the TypeScript transformation so you can extend/modify types as-needed.

πŸ… Project Goals

  1. Support converting any valid OpenAPI schema to TypeScript types, no matter how complicated.
  2. This library does NOT validate your schema, there are other libraries for that.
  3. The generated TypeScript types must match your schema as closely as possible (e.g. no renaming to PascalCase)
  4. This library should never require Java, node-gyp, or some other complex environment to work. This should require Node.js and nothing else.
  5. This library will never require a running OpenAPI server to work.

🀝 Contributing

PRs are welcome! Please see our CONTRIBUTING.md guide.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Drew Powers
Drew Powers

πŸ’» πŸ“– πŸš‡ ⚠️
Przemek Smyrdek
Przemek Smyrdek

πŸ’» πŸ“– πŸ€” ⚠️
Dan Enman
Dan Enman

πŸ› πŸ’»
Atle Frenvik Sveen
Atle Frenvik Sveen

πŸ’» πŸ“– πŸ€” ⚠️
Tim de Wolf
Tim de Wolf

πŸ’» πŸ€”
Tom Barton
Tom Barton

πŸ’» πŸ“– πŸ€” ⚠️
Sven Nicolai Viig
Sven Nicolai Viig

πŸ› πŸ’» ⚠️
Sorin Davidoi
Sorin Davidoi

πŸ› πŸ’» ⚠️
Nathan Schneirov
Nathan Schneirov

πŸ’» πŸ“– πŸ€” ⚠️
Lucien BΓ©niΓ©
Lucien BΓ©niΓ©

πŸ’» πŸ“– πŸ€” ⚠️
Boris K
Boris K

πŸ“–
Anton
Anton

πŸ› πŸ’» πŸ€” ⚠️
Tim Shelburne
Tim Shelburne

πŸ’» ⚠️
MichaΕ‚ Miszczyszyn
MichaΕ‚ Miszczyszyn

πŸ’»
Sam K Hall
Sam K Hall

πŸ’» ⚠️
Matt Jeanes
Matt Jeanes

πŸ’»
Kristofer Giltvedt Selbekk
Kristofer Giltvedt Selbekk

πŸ’»
Elliana May
Elliana May

πŸ’» ⚠️
Henrik Hall
Henrik Hall

πŸ’» πŸ“– ⚠️
Gregor Martynus
Gregor Martynus

πŸ’» ⚠️ πŸ›
Sam Mesterton-Gibbons
Sam Mesterton-Gibbons

πŸ’» πŸ› ⚠️
Rendall
Rendall

πŸ’» πŸ› ⚠️
Robert Massaioli
Robert Massaioli

πŸ’» πŸ›
Jan Kuča
Jan Kuča

πŸ’» ⚠️
Thomas Valadez
Thomas Valadez

πŸ“–
Asitha de Silva
Asitha de Silva

πŸ’» πŸ›
Mikhail Yermolayev
Mikhail Yermolayev

πŸ›
Alex Batalov
Alex Batalov

πŸ’» ⚠️
Federico Bevione
Federico Bevione

πŸ› πŸ’» ⚠️
Daisuke Yamamoto
Daisuke Yamamoto

πŸ’» πŸ› ⚠️
dnalborczyk
dnalborczyk

πŸ“– πŸ’» ⚠️
FabioWanner
FabioWanner

πŸ› πŸ’» ⚠️
Ash Smith
Ash Smith

πŸ’» πŸ› ⚠️
Micah Halter
Micah Halter

πŸ’» ⚠️ πŸ›
Yuto Yoshihara
Yuto Yoshihara

πŸ’» πŸ› ⚠️
Dakshraj Sharma
Dakshraj Sharma

πŸ’»
Shaosu Liu
Shaosu Liu

πŸ’»
Vytenis
Vytenis

πŸ’»
Eric Zorn
Eric Zorn

πŸ’» ⚠️ πŸ“–
Max Belsky
Max Belsky

πŸ’» πŸ›
Peter Bech
Peter Bech

πŸ’» πŸ›
Rusty Conover
Rusty Conover

πŸ’»
Dave Carlson
Dave Carlson

πŸ’»
ottomated
ottomated

πŸ’» πŸ›
Artem Shuvaev
Artem Shuvaev

πŸ’» πŸ›
ajaishankar
ajaishankar

πŸ“–
Dominik Dosoudil
Dominik Dosoudil

πŸ’» ⚠️
tkr
tkr

πŸ’» πŸ“–
berzi
berzi

πŸ’» πŸ“– ⚠️
Philip Trauner
Philip Trauner

πŸ’» πŸ“– ⚠️
Pavel Yermolin
Pavel Yermolin

πŸ’» πŸ“– ⚠️
Duncan Beevers
Duncan Beevers

πŸ’» πŸ› ⚠️ πŸ“–
Timofey Kukushkin
Timofey Kukushkin

πŸ’» ⚠️ πŸ›
Dmitry Semigradsky
Dmitry Semigradsky

πŸ› ⚠️ πŸ’»
Jeremy Liberman
Jeremy Liberman

πŸ’» ⚠️
Axel HernΓ‘ndez Ferrera
Axel HernΓ‘ndez Ferrera

πŸ’» πŸ› ⚠️
LoΓ―c FΓΌrhoff
LoΓ―c FΓΌrhoff

πŸ’» ⚠️ πŸ›
Bartosz SzczeciΕ„ski
Bartosz SzczeciΕ„ski

πŸ’» πŸ› ⚠️
Marco Salomone
Marco Salomone

πŸ’» ⚠️ πŸ›
Yacine Hmito
Yacine Hmito

πŸ’» ⚠️ πŸ›
Sajad Torkamani
Sajad Torkamani

πŸ“–
Marius van den Beek
Marius van den Beek

πŸ’» πŸ› ⚠️
Steven Grimm
Steven Grimm

πŸ’» πŸ› ⚠️
Erik Hughes
Erik Hughes

πŸ’» πŸ› ⚠️
Matthieu Monsch
Matthieu Monsch

πŸ’» πŸ› ⚠️
Mitchell Merry
Mitchell Merry

πŸ’» ⚠️ πŸ›
François Risoud
François Risoud

πŸ’» πŸ› ⚠️
shoffmeister
shoffmeister

πŸ“–

This project follows the all-contributors specification. Contributions of any kind welcome!

About

Generate TypeScript types from OpenAPI 3 specs

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 95.7%
  • JavaScript 4.3%