📘️ openapi-typescript

🚀 Convert [OpenAPI 3.0][openapi3] and [2.0 (Swagger)][openapi2] schemas to TypeScript interfaces using Node.js.

💅 The output is prettified with [Prettier][prettier] (and can be customized!).

👉 Works for both local and remote resources (filesystem and HTTP).

View examples:

- Stripe, OpenAPI 2.0
- Stripe, OpenAPI 3.0

Usage

$3

#### 🗄️ Reading specs from file system

``bash
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

`bash
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:

`ts
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][openapi-operationid]:

`ts
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

`bash
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:

`json
"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][npm-run-all], you can shorten this:

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

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

`bash
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? |
| --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) |

$3

`bash
npm i --save-dev openapi-typescript
`

`js
const { readFileSync } = require("fs");
const swaggerToTS = require("openapi-typescript").default;

const input = JSON.parse(readFileSync("spec.json", "utf8")); // Input can be any JS object (OpenAPI format)
const output = swaggerToTS(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][js-yaml]. If
you’re batching large folders of specs, [glob][glob] may also come in handy.

Migrating from v1 to v2

Migrating from v1 to v2

Project Goals

1. Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
1. 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)
1. 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.

[glob]: https://www.npmjs.com/package/glob
[js-yaml]: https://www.npmjs.com/package/js-yaml
[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
[npm-run-all]: https://www.npmjs.com/package/npm-run-all
[openapi-operationid]: https://swagger.io/specification/#operation-object
[openapi2]: https://swagger.io/specification/v2/
[openapi3]: https://swagger.io/specification
[prettier]: https://npmjs.com/prettier

$3

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 🐛

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