📘️ swagger-to-ts
Convert Swagger files to TypeScript interfaces using Node.js.
💅 Prettifies output with Prettier.
OpenAPI Feature | TypeScript equivalent |
---|---|
type: 'string' |
string |
type: 'number' |
number |
type: 'integer' |
number |
allOf |
TypeB extends TypeA |
oneOf |
TypeA | TypeB |
required |
(not optional) |
enum |
'a' | 'b' |
To compare actual generated output, see the example folder.
Usage
CLI
npx @manifoldco/swagger-to-ts schema.yaml --wrapper "declare namespace OpenAPI" --output schema.d.ts
# 🚀 schema.yaml -> schema.d.ts [2ms]
This will save a schema.ts
file in the current folder under the TypeScript
namespace OpenAPI
(namespaces are required because chances of
collision among specs is highly likely). The CLI can accept YAML or JSON for
the input file.
Wrapper option
There are many different ways to expose types in TypeScript. To name a few:
namespace MyNamespace {}
export namespace MyNamespace {}
declare namespace MyNamespace {}
declare module MyModule {}
The --wrapper
flag lets you specify any of the above with a string (omit
the {}
):
npx @manifoldco/swagger-to-ts schema.yaml --wrapper "namespace API"
npx @manifoldco/swagger-to-ts schema.yaml --wrapper "export namespace API"
npx @manifoldco/swagger-to-ts schema.yaml --wrapper "declare namespace API"
npx @manifoldco/swagger-to-ts schema.yaml --wrapper "declare module '@api'"
By default, wrapper is declare namespace OpenAPI2
. You can skip exposing types via a wrapper by adding the --nowrapper
flag:
npx @manifoldco/swagger-to-ts schema.yaml --nowrapper
As mentioned before, this uses Prettier to clean up output, so extra spaces are generally OK here. Prettier also will err on cleanup if you specify invalid TypeScript, letting you know on generation if anything went wrong.
Note: previous versions of the CLI tool used --namespace
and --export
.
These have both been deprecated in favor of --wrapper
.
CamelCasing properties
Within interfaces, you may want to convert snake_case
properties to
camelCase
by adding the --camelcase
flag:
npx @manifoldco/swagger-to-ts schema.yaml --camelcase --wrapper "declare namespace OpenAPI" --output schema.d.ts
# 🚀 schema.yaml -> schema.d.ts [2ms]
Generating multiple schemas
Say you have multiple schemas you need to parse. I’ve found the simplest way
to do that is to use npm scripts. In your package.json
, you can do
something like the following:
"scripts": {
"generate:specs": "npm run generate:specs:one && npm run generate:specs:two",
"generate:specs:one": "npx @manifoldco/swagger-to-ts one.yaml -o one.d.ts",
"generate:specs:two": "npx @manifoldco/swagger-to-ts two.yaml -o two.d.ts"
}
Rinse and repeat for more specs.
For anything more complicated, or for generating specs dynamically, you can also use the Node API (below).
CLI Options
Option | Alias | Default | Description |
---|---|---|---|
--wrapper |
-w |
declare namespace OpenAPI2 |
How should this export the types? |
--output [location] |
-o |
(stdout) | Where should the output file be saved? |
--swagger [version] |
-s |
2 |
Which Swagger version to use. Currently only supports 2 . |
--camelcase |
-c |
false |
Convert snake_case properties to camelCase ? |
--nowrapper |
-nw |
false |
Disables rendering a wrapper |
Node
npm i --save-dev @manifoldco/swagger-to-ts
const { readFileSync } = require('fs');
const swaggerToTS = require('@manifoldco/swagger-to-ts');
const input = JSON.parse(readFileSync('spec.json', 'utf8')); // Input can be any JS object (OpenAPI format)
const output = swaggerToTS(input, { wrapper: 'declare namespace MyAPI' }); // 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.
Node Options
Name | Type | Default | Description |
---|---|---|---|
wrapper |
string | false |
declare namespace OpenAPI2 |
How should this export the types? Pass false to disable rendering a wrapper |
swagger |
number |
2 |
Which Swagger version to use. Currently only supports 2 . |
camelcase |
boolean |
false |
Convert snake_case properties to camelCase |