/openapi-typescript

Generate TypeScript types from Swagger OpenAPI specs

Primary LanguageTypeScriptMIT LicenseMIT

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.

πŸ’… The output is prettified with Prettier (and can be customized!).

πŸ‘‰ Works for both local and remote resources (filesystem and HTTP).

View examples:

Usage

πŸ–₯️ CLI

πŸ—„οΈ Reading specs from file system

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

# 🀞 Loading spec from tests/v2/specs/stripe.yaml…
# πŸš€ schema.yaml -> schema.ts [250ms]

☁️ 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]

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"];

The reason for all the ["…"] everywhere is because OpenAPI lets you use more characters than are valid TypeScript identifiers. The goal of this project is to generate all of your schema, not merely the parts that are β€œTypeScript-safe.”

Also note that there’s a special operations interface that you can import OperationObjects by their operationId:

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

type getUsersById = operations["getUsersById"];

This is the only place where our generation differs from your schema as-written, but it’s done so as a convenience and shouldn’t cause any issues (you can still use deep references as-needed).

Thanks to @gr2m for the operations feature!

Outputting to stdout

npx openapi-typescript schema.yaml

Generating multiple schemas

In your package.json, for each schema you’d like to transform add one generate:specs:[name] npm-script. Then combine them all into one generate:specs script, like so:

"scripts": {
  "generate:specs": "npm run generate:specs:one && npm run generate:specs:two && npm run generate:specs:three",
  "generate:specs:one": "npx openapi-typescript one.yaml -o one.ts",
  "generate:specs:two": "npx openapi-typescript two.yaml -o two.ts",
  "generate:specs:three": "npx openapi-typescript three.yaml -o three.ts"
}

If you use npm-run-all, you can shorten this:

"scripts": {
  "generate:specs": "run-p generate:specs:*",

You can even specify unique options per-spec, if needed. To generate them all together, run:

npm run generate:specs

Rinse and repeat for more specs.

For anything more complicated, or for generating specs dynamically, you can also use the Node API.

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).
--immutable-types 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
--prettier-config [location] (optional) Path to your custom Prettier configuration for output
--raw-schema false Generate TS types from partial schema (e.g. having components.schema at the top level)

🐒 Node

npm i --save-dev openapi-typescript
const { readFileSync } = require("fs");
const openapiTS = require("openapi-typescript").default;

const input = JSON.parse(readFileSync("spec.json", "utf8")); // Input can be any JS object (OpenAPI format)
const output = openapiTS(input); // Outputs TypeScript defs as a string (to be parsed, or written to a file)

The Node API is a bit more flexible: it will only take a JS object as input (OpenAPI format), and return a string of TS definitions. This lets you pull from any source (a Swagger server, local files, etc.), and similarly lets you parse, post-process, and save the output anywhere.

If your specs are in YAML, you’ll have to convert them to JS objects using a library such as js-yaml. If you’re batching large folders of specs, glob may also come in handy.

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 don’t have to use .formatβ€”this 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. don’t 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

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

Przemek Smyrdek

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

Dan Enman

πŸ› πŸ’»

Atle Frenvik Sveen

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

Tim de Wolf

πŸ’» πŸ€”

Tom Barton

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

Sven Nicolai Viig

πŸ› πŸ’» ⚠️

Sorin Davidoi

πŸ› πŸ’» ⚠️

Nathan Schneirov

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

Lucien BΓ©niΓ©

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

Boris K

πŸ“–

Anton

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

Tim Shelburne

πŸ’» ⚠️

MichaΕ‚ Miszczyszyn

πŸ’»

Sam K Hall

πŸ’» ⚠️

Matt Jeanes

πŸ’»

Kristofer Giltvedt Selbekk

πŸ’»

Elliana May

πŸ’» ⚠️

Henrik Hall

πŸ’» πŸ“– ⚠️

Gregor Martynus

πŸ’» ⚠️ πŸ›

Sam Mesterton-Gibbons

πŸ’» πŸ› ⚠️

Rendall

πŸ’» πŸ› ⚠️

Robert Massaioli

πŸ’» πŸ›

Jan Kuča

πŸ’» ⚠️

Thomas Valadez

πŸ“–

Asitha de Silva

πŸ’» πŸ›

Mikhail Yermolayev

πŸ›

Alex Batalov

πŸ’» ⚠️

Federico Bevione

πŸ› πŸ’» ⚠️

Daisuke Yamamoto

πŸ’» πŸ› ⚠️

dnalborczyk

πŸ“– πŸ’» ⚠️

FabioWanner

πŸ› πŸ’» ⚠️

Ash Smith

πŸ’» πŸ› ⚠️

Micah Halter

πŸ’» ⚠️ πŸ›

Yuto Yoshihara

πŸ’» πŸ› ⚠️

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