The openapi-transformer-toolkit

As a developer, you may find yourself in a situation where you have an OpenAPI specification and need to create a JSON schema or TypeScript interfaces that reflect this specification.

Fortunately, there are a number of tools available that can help you automate this process. We have created our own solution on top of them called openapi-transformer-toolkit.

Why did we develop the openapi-transformer-toolkit?

While there are alternative libraries available for generating TypeScript interfaces and JSON schemas from OpenAPI specifications, we developed the openapi-transformer-toolkit for several reasons:

1. Separate TypeScript interface files

Alternative libraries like openapi-typescript and openapi-typescript-codegen output all TypeScript interfaces into a single file that reflects the OpenAPI schema. We based our solution on json-schema-to-typescript, but customized the output and our solution makes the generated interfaces unaware of the original OpenAPI schema.

2. Import existing TypeScript interfaces

Our toolkit also has the ability to automatically reuse already generated TypeScript interfaces in other generated interfaces, instead of duplicating them.

3. Separate JSON schema files

For JSON schema generation, we are reusing the openapi-schema-to-json-schema package, but we have customized the output to create a separate file for each JSON schema. This makes it easier to work with in some cases, as it allows for better organization and modularity.

4. Customizable logging

The openapi-transformer-toolkit uses the pino logger by default, which is a fast and versatile logging library. However, when using the toolkit programmatically, you have the option to set up a custom logger that suits your specific needs and preferences. This flexibility allows you to seamlessly integrate the toolkit into your existing logging infrastructure, ensuring a consistent and unified logging experience across your project.

Summary: automating and simplifying the generation of code from an OpenAPI specification

This toolkit is designed to simplify and automate the process of generating JSON schemas and TypeScript types based on an OpenAPI specification using CLI commands or programmatically in your code.

What is OpenAPI?

OpenAPI is a standardized, language-agnostic format for describing RESTful APIs using JSON or YAML. It enables the automatic generation of documentation, client libraries, and server stubs, improving consistency and reducing errors. The specification streamlines API development, integration, and maintenance, fostering better collaboration among developers.

How can you use JSON schemas in your project?

JSON schemas can improve data validation, documentation, and communication in a project. They help define data structure and constraints, enabling automatic validation and the generation of client and server-side code. JSON schemas also facilitate collaboration and easier integration with external systems.

How to use the openapi-transformer-toolkit?

You can start using the CLI commands for user-friendly access, or use the toolkit programmatically for increased flexibility.

Example of CLI Commands

Let’s test the first CLI command called oas2json. It will create a JSON schema based on the OpenAPI specification.

Copy to Clipboard

Let’s say this is our simple OpenAPI specification saved in openapi.yml file (JSON format is also supported).

Copy to Clipboard

The command above will generate the following files:

Address.json file:

Copy to Clipboard

Customer.json file:

Copy to Clipboard

Great! Now let’s create TypeScript interfaces. This time we will use the oas2ts command:

Copy to Clipboard

And here’s the result, Address.d.ts:

Copy to Clipboard

And Customer.d.ts:

Copy to Clipboard

You can also generate TypeScript interfaces from the JSON schemas if you need to.

Copy to Clipboard

Example of Programmatic Usage

You can also use the package programmatically by importing the necessary functions. First, let’s install the package in your project:

Copy to Clipboard

Now you can import the methods:

Copy to Clipboard

You use them in a similar way to the CLI commands. So, to create JSON schemas from the OpenAPI specification, use the following code:

Copy to Clipboard

You can create TypeScript files from the OpenAPI specification:

Copy to Clipboard

Or you create TypeScript files from the JSON schemas, if you need to:

Copy to Clipboard

Both functions would produce identical results (those shown above).

Using JSON Schemas in Fastify and React Hook Form

In this section, we’ll demonstrate how to use the generated JSON schemas in a Fastify server and a React application with the react-hook-form for form validation.

Getting Fastify to use the JSON schema to validate the incoming request body

Copy to Clipboard

Now your Fastify server will use the JSON schema to validate the incoming request body for the /customer endpoint.

Getting the React Hook Form to use the JSON schema to validate input fields

Copy to Clipboard

In this example, we’ve used the Address.json schema to create an address form with the react-hook-form. The form will be validated using the schema, and errors will be displayed accordingly.

Ongoing enhancements

In the future, we aim to incorporate support for additional validation outputs, making the toolkit even more powerful and adaptable.


The OpenAPI Transformer Kit created by NearForm is a practical addition to your API development toolkit. It quickly streamlines the generation of JSON schemas and TypeScript types from OpenAPI specifications, allowing you to focus on the core aspects of crafting reliable APIs.

Give the OpenAPI Transformer Kit a try today and don’t hesitate to share your experience with us. We’re always open to your feedback and suggestions for future improvements.

Share Me

Related Reading


Don’t miss a beat

Get all the latest NearForm news, from technology to design. Sign up for our newsletter.

Follow us for more information on this and other topics.