Swagger/OpenAPI генерация TypeScript

Swagger/OpenAPI генерация для TypeScript: автоматизация создания API-клиентов

При разработке современных веб-приложений на TypeScript часто возникает задача интеграции с REST API, описанным через спецификации OpenAPI (ранее известные как Swagger). Ручное написание типов, интерфейсов и клиентского кода не только отнимает много времени, но и чревато ошибками, особенно при изменении бэкенда. На помощь приходят инструменты автоматической генерации TypeScript-кода из OpenAPI-спецификаций. В этой статье мы рассмотрим три наиболее популярных решения: openapi-typescript, orval и swagger-typescript-api, а также сравним их возможности.

Зачем нужна генерация TypeScript из OpenAPI?

Основная цель — синхронизация типов и клиентского кода между фронтендом и бэкендом. Преимущества автоматической генерации:

Типобезопасность: Все эндпоинты, параметры запросов и ответы получают строгие типы TypeScript.
Актуальность: При изменении спецификации достаточно перегенерировать код, не внося правки вручную.
Ускорение разработки: Разработчик получает готовые функции для вызова API с автодополнением (IntelliSense).
Минимизация ошибок: Исключаются опечатки в именах полей и несоответствия типов.

openapi-typescript

Библиотека openapi-typescript (от создателей openapi-fetch) — это легковесный генератор типов. Она создаёт только TypeScript-интерфейсы и типы, не генерируя клиентский код для вызовов API. Это идеальный выбор для проектов, где нужно строго типизировать данные, но способ вызова API остаётся на усмотрение разработчика (например, через fetch или axios).

Установка:

npm install -D openapi-typescript

Пример использования (генерируем типы из файла spec.yaml):

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

В результате получается файл с типами, которые можно импортировать:

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

// Тип для ответа от GET /users
type UsersResponse = paths['/users']['get']['responses'][200]['content']['application/json'];

Плюсы: Минимализм, быстрая генерация, отличная поддержка complex схем (allOf, oneOf).
Минусы: Нет готовых функций для вызова API, требуется дополнительная обёртка.

orval

Orval — это мощный генератор, который создаёт не только типы, но и полностью рабочие React-хуки, а также клиенты для axios, fetch или Angular. Он особенно полезен в React-проектах, где используется React Query (TanStack Query).

Установка:

npm install -D orval

Конфигурация в файле orval.config.ts:

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

Запуск генерации:

npx orval

Пример сгенерированного хука:

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

function UsersList() {
  const { data, isLoading, error } = useGetUsers();
  // data будет типизирован автоматически
}

Плюсы: Готовая интеграция с React Query, поддержка мутаций, автоматическое управление кэшированием.
Минусы: Большой объём сгенерированного кода, привязанность к конкретному HTTP-клиенту.

swagger-typescript-api

Библиотека swagger-typescript-api предлагает гибкую генерацию: можно получить как простые типы, так и полноценный API-клиент с поддержкой различных HTTP-клиентов (axios, fetch). Отличительная особенность — возможность кастомизации шаблонов генерации.

Установка:

npm install -D swagger-typescript-api

Пример генерации с клиентом на axios:

npx swagger-typescript-api -p ./swagger.json -o ./src/api -n myApi.ts --axios

Использование в коде:

import { MyApi } from './src/api/myApi';

const api = new MyApi({ baseURL: 'https://api.example.com' });
const users = await api.users.getUsers(); // автодополнение сработает

Плюсы: Гибкие шаблоны (Handlebars), поддержка модульной генера