openapi-typescript-atlefix
v2.4.3
Published
Generate TypeScript types from Swagger OpenAPI specs
Downloads
20
Maintainers
Readme
📘️ 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": {
"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? |
| --prettier-config [location]
| | | (optional) Path to your custom Prettier configuration for output |
Node
npm i --save-dev openapi-typescript
const { 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.
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 }): 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!
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!