Как выполняется генерация TypeScript-клиента и моделей данных по YAML-описанию OpenAPI?

Что такое OpenAPI и зачем генерировать клиент?

OpenAPI (ранее Swagger) — это стандарт описания REST API в формате YAML или JSON. Он содержит информацию о путях, методах, параметрах, ответах и схемах данных. Вместо ручного написания клиентского кода, который может расходиться с реальным API, разработчики используют генераторы. Это экономит время и уменьшает количество ошибок, связанных с несоответствием типов или изменением контракта.

Как работает генерация?

Инструмент, например openapi-generator-cli, читает YAML-файл и создает файлы TypeScript. Для каждого эндпоинта генерируется функция, которая принимает параметры и возвращает типизированный ответ. Для каждой схемы данных создается интерфейс или класс. Генерация происходит по шаблонам, которые можно настраивать под конкретный проект.

// Пример команды для генерации
npx @openapitools/openapi-generator-cli generate \
  -i api.yaml \
  -g typescript-fetch \
  -o src/generated

После выполнения команды в папке src/generated появятся файлы с моделями и клиентом. Например, для схемы User будет создан интерфейс:

export interface User {
  id: number;
  name: string;
  email: string;
}

А для эндпоинта GET /users/{id} — функция:

export async function getUserById(id: number): Promise<User> {
  const response = await fetch(`/users/${id}`);
  return response.json();
}

Практическое применение

Генерация особенно полезна в больших проектах с множеством эндпоинтов и сложными моделями. Она обеспечивает единый источник правды — спецификацию, из которой автоматически обновляется клиент при изменении API. Это упрощает поддержку и интеграцию между командами фронтенда и бэкенда.

Вывод

Используйте генерацию TypeScript-клиента по OpenAPI, когда хотите автоматизировать создание типизированного кода, избежать ручных ошибок и поддерживать актуальность клиента относительно документации API. Это стандартный подход в современных проектах с REST-архитектурой.