[![version(scoped)](https://img.shields.io/npm/v/openapi-typescript.svg)](https://www.npmjs.com/package/openapi-typescript) [![npm downloads (weekly)](https://img.shields.io/npm/dw/openapi-typescript)](https://www.npmjs.com/package/openapi-typescript) [![codecov](https://codecov.io/gh/drwpow/openapi-typescript/branch/master/graph/badge.svg)](https://codecov.io/gh/drwpow/openapi-typescript) [![All Contributors](https://img.shields.io/badge/all_contributors-36-orange.svg?style=flat-square)](#contributors-) # πŸ“˜οΈ 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](./examples/stripe-openapi2.ts) - [Stripe, OpenAPI 3.0](./examples/stripe-openapi3.ts) ## Usage ### πŸ–₯️ CLI #### πŸ—„οΈ Reading specs from file system ```bash 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](https://github.com/sharmarajdaksh) for the glob feature!_ #### ☁️ 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] ``` _Note: for obvious reasons, globbing doesn’t work for remote schemas_ _Thanks to [@psmyrdek](https://github.com/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 ``` #### 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` | `-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 | | `--raw-schema` | | `false` | Generate TS types from partial schema (e.g. having `components.schema` at the top level) | ### 🐒 Node ```bash npm i --save-dev openapi-typescript ``` ```js 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][js-yaml]. If you’re batching large folders of specs, [glob][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: ```yaml 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: ```js 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 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](./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-format]: https://swagger.io/specification/#data-types [openapi-operationid]: https://swagger.io/specification/#operation-object [openapi2]: https://swagger.io/specification/v2/ [openapi3]: https://swagger.io/specification [prettier]: https://npmjs.com/prettier ### Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/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
πŸ’» πŸ› ⚠️

Dakshraj Sharma
πŸ’»
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!