OpenAPI Transformer Toolkit

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

Table of Contents

• Installation
• CLI
• Programmatic Usage
  • Generate JSON Schemas from OpenAPI
  • Generate TypeScript Types from OpenAPI
  • Generate TypeScript Types from JSON Schemas
• Example

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

CLI

The package includes CLI commands for easier usage. Use the openapi-transformer-toolkit executable followed by the command and required options:

• Generate JSON schemas from OpenAPI:
  • openapi-transformer-toolkit oas2json -i < input > -o < output >
• Generate TS types from OpenAPI:
  • openapi-transformer-toolkit oas2ts -i < input > -o < output > [-c < config >]
• Generate TS types from JSON schemas:
  • openapi-transformer-toolkit json2ts -i < input > -o < output > [-c < config >]

The -c arguments accepts a configuration file for the json-schema-to-typescript package.

For example:

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

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

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

Programmatic Usage

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

import { oas2json, oas2ts, json2ts } 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';

oas2json(openAPIPath, schemasPath);

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:

const openAPIPath = 'path/to/openapi.yml';
const tsTypesPath = 'path/to/output/types';

await oas2ts(openAPIPath, tsTypesPath);

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:

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

await json2ts(schemasPath, tsTypesPath);

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

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