📘️ 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?
--camelcase	-c	false	Convert snake_case properties to camelCase
--no-warning		false	Disables “autogenerated file” warning at the top of generated files
--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
camelcase	boolean	false	Convert snake_case properties to camelCase
propertyMapper	function	undefined	Allows you to further manipulate how properties are parsed. See below.

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.

This is a function that, if specified, is called for each property and allows you to change how swagger-to-ts 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 propertyMapper = (swaggerDefinition: Swagger2Definition, property: Property): Property => ({
  ...property,
  optional: getNullable(swaggerDefinition),
});

const output = swaggerToTS(swagger, { propertyMapper });