Swagger/OpenAPI Generation for TypeScript: Libraries and Tools

Swagger/OpenAPI Generation for TypeScript: Automating API Client Creation

When developing modern web applications in TypeScript, the need often arises to integrate with a REST API described via OpenAPI specifications (formerly known as Swagger). Manually writing types, interfaces, and client code is not only time-consuming but also error-prone, especially when the backend changes. Automatic code generation tools from OpenAPI specifications come to the rescue. In this article, we will look at three of the most popular solutions: openapi-typescript, orval, and swagger-typescript-api, and compare their capabilities.

Why Generate TypeScript from OpenAPI?

The main goal is to synchronize types and client code between the frontend and backend. Advantages of automatic generation:

• Type Safety: All endpoints, request parameters, and responses receive strict TypeScript types.
• Up-to-date: When the specification changes, simply regenerate the code without manual edits.
• Development Speed: The developer gets ready-made functions for calling the API with autocompletion (IntelliSense).
• Error Minimization: Typos in field names and type mismatches are eliminated.

openapi-typescript

The openapi-typescript library (from the creators of openapi-fetch) is a lightweight type generator. It only creates TypeScript interfaces and types, without generating client code for API calls. This is an ideal choice for projects where data needs strict typing, but the method of calling the API is left to the developer (e.g., via fetch or axios).

Installation:

npm install -D openapi-typescript

Usage example (generating types from a spec.yaml file):

npx openapi-typescript ./spec.yaml -o ./types/api.ts

The result is a file with types that can be imported:

import type { paths } from './types/api';

// Type for the response from GET /userstype UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Pros: Minimalism, fast generation, excellent support for complex schemas (allOf, oneOf).
Cons: No ready-made functions for API calls, requires an additional wrapper.

orval

Orval is a powerful generator that creates not only types but also fully functional React hooks, as well as clients for axios, fetch, or Angular. It is especially useful in React projects using React Query (TanStack Query).

Installation:

npm install -D orval

Configuration in the orval.config.ts file:

export default {  petstore: {    input: './swagger.yaml',    output: {      target: './src/generated',      client: 'react-query', // or 'axios', 'fetch', 'angular'    },  },};

Running the generation:

npx orval

Example of a generated hook:

import { useGetUsers } from './src/generated/users';

function UsersList() {  const { data, isLoading, error } = useGetUsers();  // data will be automatically typed}

Pros: Ready integration with React Query, support for mutations, automatic cache management.
Cons: Large volume of generated code, tied to a specific HTTP client.

swagger-typescript-api

The swagger-typescript-api library offers flexible generation: you can get both simple types and a full-fledged API client with support for various HTTP clients (axios, fetch). A distinctive feature is the ability to customize generation templates.

Installation: