OpenAPI Transformer Toolkit

Effortlessly automate your API design-first development workflow by generating JSON schemas and TypeScript types from an OpenAPI specification.

Table of Contents

• Installation
• CLI
  • Create JSON Schema From OpenAPI Definitions
    • Usage
    • Example
    • Options
  • Generate TypeScript types from OpenAPI Defintions
    • Usage
    • Example
    • Options
  • Generate TypeScript types from JSON schemas
    • Usage
    • Example
    • Options
  • Create TypeScript JSON Schema From OpenAPI Definitions
    • Usage
    • Example
    • Options
• Programmatic Usage
  • Generate JSON Schemas from OpenAPI
  • Generate TypeScript Types from OpenAPI
  • Generate TypeScript Types from JSON Schemas
  • Generate TypeScript exported JSON Schemas from OpenAPI
• Example
• Additional Configuration

Installation

You can install the package with npm (or another package manager):

$ npm install openapi-transformer-toolkit

If you want to install it globally, you can provide the -g flag.

Alternatively, you can run the CLI using npx:

$ npx openapi-transformer-toolkit [command] [options]

CLI

For easier usage, the package includes the openapi-transformer-toolkit executable you can use from your CLI.

Create JSON Schema From OpenAPI Definitions

Using the oas2json command you can create JSON schema records from OpenAPI definitions.

Usage

openapi-transformer-toolkit oas2json [options]

Example

$ openapi-transformer-toolkit oas2json -i ./openapi.yml -o ./schemas -p paths

Options

-i, --input <string>       Specify the path to the OpenAPI file
-o, --output <string>      Specify the path to the folder where you wish to output the schemas
-p, --properties <string>  Specify the properties/definitions in the OpenAPI file to convert in a comma-separated list (optional)
-h, --help                 Display help for command

Generate TypeScript types from OpenAPI Defintions

Using the oas2ts command you can create TypeScript types from your OpenAPI definitions.

Usage

openapi-transformer-toolkit oas2ts [options]

Example

$ openapi-transformer-toolkit oas2ts -i ./openapi.yml -o ./types

$ openapi-transformer-toolkit oas2ts -i ./openapi.yml -o ./types -c ./config.json

Options

-i, --input <string>     Path to the OpenAPI file
-o, --output <string>    Path to the folder where to output the TypeScript types
-c, --config <string>    Path to the JSON/JS config file
-h, --help               Display help for command

See Additional Configuration for the -c, --config option.

Generate TypeScript types from JSON schemas

Using the json2ts command you can create TypeScript types from your JSON Schema definitions.

Usage

openapi-transformer-toolkit json2ts [options]

Example

$ openapi-transformer-toolkit json2ts -i ./schemas -o ./types

$ openapi-transformer-toolkit json2ts -i ./schemas -o ./types -c ./config.json

Options

-i, --input <string>        Path to the JSON schemas folder
-o, --output <string>       Path to the folder where to output the TS files
-c, --config <string>       Path to the JSON/JS config file
-h, --help                  Display help for command

See Additional Configuration for the -c, --config option.

Create TypeScript JSON Schema From OpenAPI Definitions

Using the oas2tson command you can create Typescript exported JSON schema records from OpenAPI definitions.

Usage

openapi-transformer-toolkit oas2tson [options]

Example

$ openapi-transformer-toolkit oas2tson -i ./openapi.yml -o ./schemas -p paths

Options

-i, --input <string>       Specify the path to the OpenAPI file
-o, --output <string>      Specify the path to the folder where you wish to output the schemas
-p, --properties <string>  Specify the properties/definitions in the OpenAPI file to convert in a comma-separated list (optional)
-h, --help                 Display help for command

Programmatic Usage

You can also use the package programmatically by importing the necessary functions:

import { oas2json, oas2ts, json2ts, oas2tson } from 'openapi-transformer-toolkit'

Generate JSON Schemas from OpenAPI

To generate JSON schemas from your OpenAPI specification, provide the path to the OpenAPI file and the output directory for the generated schemas:

const openAPIPath = 'path/to/openapi.yml'
const schemasPath = 'path/to/output/schemas'
const propertiesToConvert = 'paths'

oas2json(openAPIPath, schemasPath, propertiesToExport)

Generate TypeScript Types from OpenAPI

To generate TypeScript types from the OpenAPI specification, provide the path to the OpenAPI file and the output directory for the TypeScript types. Optionally, the third parameter can contain configuration options

const openAPIPath = 'path/to/openapi.yml'
const tsTypesPath = 'path/to/output/types'
//
const options = {
  bannerComment: 'Custom banner content'
}

await oas2ts(openAPIPath, tsTypesPath, options)

Generate TypeScript Types from JSON Schemas

To generate TypeScript types from the generated JSON schemas, provide the path to the JSON schema directory and the output directory for the TypeScript types. Optionally, the third parameter can contain configuration options

const schemasPath = 'path/to/output/schemas'
const tsTypesPath = 'path/to/output/types'

await json2ts(schemasPath, tsTypesPath)

Generate TypeScript exported JSON Schemas from OpenAPI

To generate TypeScript exported JSON schemas from your OpenAPI specification, provide the path to the OpenAPI file and the output directory for the generated schemas:

const openAPIPath = 'path/to/openapi.yml'
const schemasPath = 'path/to/output/schemas'
const propertiesToConvert = 'paths'

oas2tson(openAPIPath, schemasPath, propertiesToExport)

Example

The example folder contains an example OpenAPI specification and the generated JSON schemas and TypeScript types. To generate the JSON schemas and TypeScript types from the example OpenAPI specification, run:

$ npm run oas2json

and then:

$ npm run oas2ts

or:

$ npm run json2ts

$ npm run oas2json

And to generate TypeScript exported JSON schema from example OpenAPI specification, run:

$ npm run oas2tson

The generated JSON schemas and TypeScript types will be saved in the output schemas and types folders respectively.

Additional Configuration

OpenAPI Transformer Toolkit package utilises the json-schema-to-typescript package.

This package allows you to specify additional options which can be passed to the command when executing, for example to affect the style of output, or change how additionalProperties from your API definition is handled.

To utilise this feature, OpenAPI Transformer Toolkit can read these additional options from a file when being used from a CLI. An example of this can be found here.

When using OpenAPI Transformer Toolkit programmatically, these options can optionally be supplied as the third argument to the oas2ts and json2ts functions.