Awesome Open Source
Awesome Open Source

version(scoped) npm downloads (weekly) codecov

All Contributors

openapi-typescript

Convert OpenAPI 3.0 and 2.0 (Swagger) schemas to TypeScript interfaces using Node.js.

Features

  • OpenAPI 3.0
  • Swagger 2.0
  • Supports YAML and JSON schema formats
  • Supports loading via remote URL (simple authentication supported with the --auth flag)
  • Supports remote references: $ref: "external.yaml#components/schemas/User"
  • Formats using Prettier
  • TypeScript 4.0 features

Examples

Usage

CLI

Reading specs from file system

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

#  Loading spec from schema.yaml
#  schema.yaml -> schema.ts [250ms]

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]

Note: if generating a single schema, --output must be a file (preferably *.ts). If using globs, --output must be a directory.

Thanks to @sharmarajdaksh for the glob feature!

Reading specs from remote resource

npx openapi-typescript https://petstore.swagger.io/v2/swagger.json --output petstore.ts

#  Loading spec from https://petstore.swagger.io/v2/swagger.json
#  https://petstore.swagger.io/v2/swagger.json -> petstore.ts [650ms]

Note: globbing doesnt work for remote schemas because there is no reliable way to determine a list of files to select from a remote file system.

Thanks to @psmyrdek for the remote spec feature!

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.

Also note that theres a special operations interface that you can import OperationObjects by their operationId:

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

type getUsersById = operations["getUsersById"];

Even though operations isnt present in your original schema, its a simple convenience and wont disrupt any of your other types.

Thanks to @gr2m for the operations feature!

openapi-typescript-fetch

The generated spec can also be used with openapi-typescript-fetch which implements a typed fetch client for openapi-typescript.

import { paths } from "./petstore";

import { Fetcher } from "openapi-typescript-fetch";

// declare fetcher for paths
const fetcher = Fetcher.for<paths>()

// global configuration
fetcher.configure({
  baseUrl: "https://petstore.swagger.io/v2",
  init: {
    headers: {
      ...
    },
  },
  use: [...] // middlewares
})

// create fetch operations
const findPetsByStatus = fetcher.path("/pet/findByStatus").method("get").create()
const addPet = fetcher.path("/pet").method("post").create()

// fetch
try {
  const { status, data: pets } = await findPetsByStatus({
    status: ["available", "pending"],
  })
  await addPet({ ... })
} catch(e) {
  // check which operation threw the exception
  if (e instanceof addPet.Error) {
    // get discriminated union { status, data }
    const error = e.getActualType()
    if (error.status === 400) {
      error.data.validationErrors // 400 response data
    } else if (error.status === 500) {
      error.data.errorMessage // 500 response data
    } else {
      ...
    }
  }
}

Outputting to stdout

Simply omit the --output flag to return to stdout:

npx openapi-typescript schema.yaml

CLI Options

Option Alias Default Description
--output [location] -o (stdout) Where should the output file be saved?
--auth [token] (optional) Provide an auth token to be passed along in the request (only if accessing a private schema)
--header -x (optional) Provide an array of or singular headers as an alternative to a JSON object. Each header must follow the key: value pattern
--headersObject -h (optional) Provide a JSON object as string of HTTP headers for remote schema request. This will take priority over --header
--httpMethod -m GET (optional) Provide the HTTP Verb/Method for fetching a schema from a remote URL
--immutable-types -it false (optional) Generates immutable types (readonly properties and readonly array)
--additional-properties -ap false (optional) Allow arbitrary properties for all schema objects without additionalProperties: false
--default-non-nullable false (optional) Treat schema objects with default values as non-nullable
--prettier-config [location] -c (optional) Path to your custom Prettier configuration for output
--export-type false (optional) Export type instead of interface
--support-array-length false (optional) Generate tuples using array minItems / maxItems
--make-paths-enum -pe false (optional) Generate an enum of endpoint paths
--path-params-as-types false (optional) Substitute path parameter names with their respective types
--raw-schema false Generate TS types from partial schema (e.g. having components.schema at the top level)
--version Force OpenAPI version with --version 3 or --version 2 (required for --raw-schema when version is unknown)

Node

npm i --save-dev openapi-typescript
import fs from "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 youre 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 isnt supported in the Node.js API; either use the CLI or convert to JSON using js-yaml first.

As of v4.0, openapiTS() is an async function.

Custom Formatter

If using the Node.js API, you can optionally pass a formatter to openapi-typescript. This is useful if you want to override the default types and substitute your own.

For example, say your schema has the following property:

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

By default, this will generate a type updated_at?: string;. But we can override this by passing a formatter to the Node API, like so:

const types = openapiTS(mySchema, {
  formatter(node: SchemaObject) {
    if (node.format === "date-time") {
      return "Date"; // return the TypeScript Date type, as a string
    }
  // for all other schema objects, let openapi-typescript decide (return undefined)
});

This will generate updated_at?: Date instead. Note that you will still have to do the parsing of your data yourself. But this will save you from having to also update all your types.

Note: you dont have to use .formatthis is just an example! You can use any property on a schema object to overwrite its generated type if desired.

Project Goals

  1. Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
  2. The generated TypeScript types must match your schema as closely as possible (i.e. dont convert names to PascalCase or follow any TypeScript-isms; faithfully reproduce your schema as closely as possible, capitalization and all)
  3. This library is a TypeScript generator, not a schema validator.

Contributing

PRs are welcome! Please see our CONTRIBUTING.md guide. Opening an issue beforehand to discuss is encouraged but not required.

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 Bni
Lucien Bni

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 Kua
Jan Kua

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

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

Alternatives To Openapi Typescript
Select To Compare


Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Typescript (268,600
Types (29,942
Schema (14,677
Swagger (8,120
Openapi (3,505
Stripe (3,423