📘️ 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 this feature!
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":
If you use npm-run-all, you can shorten this:
"scripts":
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? |
--prettier-config [location] |
(optional) Path to your custom Prettier configuration for output |
Node
npm i --save-dev openapi-typescript
const readFileSync = ;const swaggerToTS = ; const input = JSON; // Input can be any JS object (OpenAPI format)const output = ; // 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.
PropertyMapper
In order to allow more control over how properties are parsed, and to specifically handle x-something
-properties, the
propertyMapper
option may be specified as the optional 2nd parameter.
This is a function that, if specified, is called for each property and allows you to change how openapi-typescript handles parsing of Swagger files.
An example on how to use the x-nullable
property to control if a property is optional:
const getNullable = d: key: string: any : { const nullable = d"x-nullable"; if typeof nullable === "boolean" return nullable; return true;}; const output = ;
Thanks to @atlefren for this feature!
Migrating from v1 to v2
Project Goals
- Support converting any OpenAPI 3.0 or 2.0 (Swagger) schema to TypeScript types, no matter how complicated
- 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) - 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):
This project follows the all-contributors specification. Contributions of any kind welcome!