π 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:
npx openapi-typescript schema.yaml --output schema.ts
# π€ Loading spec from tests/v2/specs/stripe.yamlβ¦
# π schema.yaml -> schema.ts [250ms]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!
npx openapi-typescript schema.yamlIn 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:specsRinse and repeat for more specs.
For anything more complicated, or for generating specs dynamically, you can also use the Node API.
| 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 |
npm i --save-dev openapi-typescriptconst { readFileSync } = require("fs");
const swaggerToTS = require("openapi-typescript");
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. If youβre batching large folders of specs, glob may also come in handy.
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 }): boolean => {
const nullable = d["x-nullable"];
if (typeof nullable === "boolean") {
return nullable;
}
return true;
};
const output = swaggerToTS(swagger, {
propertyMapper: (swaggerDefinition, property): Property => ({
...property,
optional: getNullable(swaggerDefinition),
}),
});Thanks to @atlefren for this feature!
- 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
PascalCaseor 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.
PRs are welcome! Please see our CONTRIBUTING.md guide. Opening an issue beforehand to discuss is encouraged but not required.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!