Simplify Your API Development with Our OpenAPI Code Generation ToolSimplify Your API Development with Our OpenAPI Code Generation ToolSimplify Your API Development with Our OpenAPI Code Generation Tool

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 .

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:

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.

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

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.

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.

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.

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.

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.

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

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

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

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

openapi: 3.0.3
info:
  title: Example OpenAPI
  version: 1.0.11
paths: {}
components:
  schemas:
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        address:
          type: array
          items:
            $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string

The command above will generate the following files: Address.json file:

import { Address } from './Address'

export interface Customer {
  id?: number;
  username?: string;
  address?: Address[];
  [k: string]: unknown;
}

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

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

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

$ npm install openapi-transformer-toolkit

Now you can import the methods:

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

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

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

oas2json(openAPIPath, schemasPath);

You can create TypeScript files from the OpenAPI specification:

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

await oas2ts(openAPIPath, tsTypesPath);

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

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

await json2ts(schemasPath, tsTypesPath);

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

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.

import Fastify from 'fastify';
import CustomerSchema from './Customer.json' assert { type: 'json' };
import AddressSchema from './Address.json' assert { type: 'json' };

const fastify = Fastify({
    logger: true,
});

fastify.addSchema(CustomerSchema);
fastify.addSchema(AddressSchema);

fastify.post('/customer', {
        schema: {
            body: {
                $ref: 'Customer.json#',
            },
        },
    },
    async (request, reply) => {
        const customer = request.body;
        return { message: 'Customer created successfully', customer };
    }
);

fastify.listen({ port: 3000 });

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

import React from 'react';
import { useForm } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import convertToYup from "json-schema-yup-transformer";
import AddressJson from "./Address.json";

const App = () => {
    const { register, handleSubmit, formState: {errors} } = useForm({
        resolver: yupResolver(convertToYup(AddressJson)),
    });

    const onSubmit = (data) => {
        console.log('Submitted data:', data);
    };

    return (
        <div>
            <h1>Address Form</h1>
            <form onSubmit={handleSubmit(onSubmit)}>
                <label htmlFor="street">Street</label>
                <input name="street" {...register("street")} />
                {errors.street && <p>{errors.street.message}</p>}
                <br />

                <label htmlFor="city">City</label>
                <input name="city" {...register("city")} />
                {errors.city && <p>{errors.city.message}</p>}
                <br />

                <label htmlFor="state">State</label>
                <input name="state" {...register("state")} />
                {errors.state && <p>{errors.state.message}</p>}
                <br />

                <label htmlFor="zip">ZIP Code</label>
                <input name="zip" {...register("zip")} />
                {errors.zip && <p>{errors.zip.message}</p>}
                <br />

                <button type="submit">Submit</button>
            </form>
        </div>
    );
};
export default App

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.