Convert Swagger files to TypeScript interfaces using Node.js.

💅 Prettifies output with Prettier.

To compare actual generated output, see the example folder.

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.

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.

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]

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).

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.