12th May 2023
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.
Let’s say this is our simple OpenAPI specification saved in
openapi.yml file (JSON format is also supported).
The command above will generate the following files:
Great! Now let’s create TypeScript interfaces. This time we will use the
And here’s the result,
You can also generate TypeScript interfaces from the JSON schemas if you need to.
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:
Now you can import the methods:
You use them in a similar way to the CLI commands. So, to create JSON schemas from the OpenAPI specification, use the following code:
You can create TypeScript files from the OpenAPI specification:
Or you create TypeScript files from the JSON schemas, if you need to:
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
Now your Fastify server will use the JSON schema to validate the incoming request body for the
Getting the React Hook Form to use the JSON schema to validate input fields
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.
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.