Top 10 OpenAPI TypeScript Solutions for Efficient Development

Looking for a Postman alternative?

Try APIDog, the Most Customizable Postman Alternative, where you can connect to thousands of APIs right now!

Download Apidog

Introduction

When it comes to software development, the OpenAPI specification plays a vital role in designing and documenting APIs. It provides a standardized way to describe and communicate about APIs, making it easier for developers to understand how to interact with them. However, one challenge that developers often face is converting the OpenAPI specification to a TypeScript JSON schema.

The need to convert OpenAPI specification to TypeScript JSON schema arises when developers want to generate TypeScript interfaces and models from the specification. This allows for better type safety and ensures that the code adheres to the API contract defined in the OpenAPI specification. However, finding existing solutions that meet this requirement can be a daunting task.

Enter openapi-ts-json-schema, a library specifically designed to convert OpenAPI specification to TypeScript JSON schema. This library provides a straightforward and efficient solution for developers who need to generate TypeScript interfaces and models from an OpenAPI specification.

Converting OpenAPI Specification to TypeScript JSON Schema

The process of converting an OpenAPI specification to TypeScript JSON schema involves a few important steps. Let’s explore these steps in detail:

1. Resolving external or remote references: The first step in the process is to resolve any external or remote references present in the OpenAPI definition. This is where the @apidevtools/json-schema-ref-parser library comes into play. It allows us to resolve and dereference these references, ensuring that we have a complete and standalone OpenAPI definition.
2. Converting resolved references to JSON schema: Once the external or remote references have been resolved, we can proceed to convert them to JSON schema format. For this task, we can utilize libraries like @openapi-contrib/openapi-schema-to-json-schema and openapi-jsonschema-parameters. These libraries handle the conversion of OpenAPI-specific constructs to JSON schema, so we can work with a standardized schema format.
3. Generating TypeScript JSON schema files: With the resolved references converted to JSON schema, we can now generate TypeScript JSON schema files. The openapi-ts-json-schema library automates this process, allowing us to generate one TypeScript JSON schema file for each definition in the OpenAPI specification.
4. Storing generated schema files: To keep things organized, it’s a good practice to store the generated schema files in a folder structure that mirrors the original OpenAPI definition. This makes it easier to locate and manage the files. The openapi-ts-json-schema library provides functionality to automatically store the schema files in a directory structure that reflects the structure of the original OpenAPI definition.

Example of Generated TypeScript JSON Schema Files

Let’s take a look at an example of how the generated TypeScript JSON schema file looks like:

// pets.schema.ts
export interface Pet {
  id: number;
  name: string;
  tag?: string;
}

// users.schema.ts
export interface User {
  id: number;
  username: string;
  email: string;
}

In the above example, we have two TypeScript interfaces, Pet and User, which correspond to the definitions in the OpenAPI specification. These interfaces provide type safety and allow us to work with objects that adhere to the API contract defined in the specification.

To use these generated TypeScript JSON schema files in a TypeScript application, simply import them into your code:

import { Pet, User } from './schemas';

// Create a new pet
const newPet: Pet = {
  id: 1,
  name: 'Fido',
  tag: 'dog',
};

// Update a user
const updateUser = (user: User): User => {
  // update logic
};

// Use the imported types in your code

By importing the TypeScript JSON schema files, we gain access to the defined interfaces, allowing us to work with strongly-typed objects that match the API contract. This improves developer productivity by providing autocompletion, type checking, and better error handling.

The Need for Native Support in TypeScript

Although the process of generating TypeScript JSON schema files from the OpenAPI specification works well with the openapi-ts-json-schema library, there is still a need for native support in TypeScript. Currently, importing JSON schema files in TypeScript and inferring types from any JSON schema is not straightforward.

Native support in TypeScript would provide several advantages. It would eliminate the need for an additional library like openapi-ts-json-schema and simplify the process of working with JSON schema files. Additionally, native support would enable better integration with other tools and frameworks that rely on JSON schema, further enhancing developer productivity.

Conclusion

In this article, we discussed the process of converting OpenAPI specification to TypeScript JSON schema. We explored the steps involved, from resolving external references to generating TypeScript JSON schema files. We also provided an example of how the generated TypeScript JSON schema file looks like and how it can be used in a TypeScript application.

While the openapi-ts-json-schema library provides a solution for generating TypeScript JSON schema files, there is still a need for native support in TypeScript. With native support, developers can seamlessly import JSON schema files and infer types from any JSON schema, improving the development experience and productivity.

We encourage readers to check out the openapi-ts-json-schema library and engage in discussions if it fits their use case. By sharing feedback and ideas, we can collectively contribute to the growth and improvement of TypeScript's support for JSON schema integration.

Looking for a Postman alternative?

Try APIDog, the Most Customizable Postman Alternative, where you can connect to thousands of APIs right now!

Download Apidog