openapi-typescript-atlefix
v2.4.3TypeScript
Generate TypeScript types from Swagger OpenAPI specs
0/weekUpdated 3 years agoISCUnpacked: 98.6 KB
Published by atlefren
npm install openapi-typescript-atlefix
๐๏ธ 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 this feature!_
#### Generating multiple schemas
In your
, 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 |
| :----------------------------- | :---- | :------: | :--------------------------------------------------------------- |
|
| -o | (stdout) | Where should the output file be saved? |
| --prettier-config [location] | | | (optional) Path to your custom Prettier configuration for output |$3
`bash
npm i --save-dev openapi-typescript
`js
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][js-yaml]. If
youโre batching large folders of specs, [glob][glob] may also come in handy.
#### PropertyMapper
In order to allow more control over how properties are parsed, and to specifically handle
-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:`js
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
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
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
[openapi2]: https://swagger.io/specification/v2/
[namespace]: https://www.typescriptlang.org/docs/handbook/namespaces.html
[npm-run-all]: https://www.npmjs.com/package/npm-run-all
[openapi3]: https://swagger.io/specification
[prettier]: https://npmjs.com/prettier
$3
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification.
Contributions of any kind welcome!