OpenAPI как рабочий инструмент фронтенда: генерация типизированных клиентов и моковСтатья · дайджест за 12 ноября
Фотореалистичный 3D-рендеринг прозрачной матрицы контракта API, формирующей типизированные блоки
Статья4 раздела≈ 7 мин

OpenAPI как рабочий инструмент фронтенда: генерация типизированных клиентов и моков

Вокруг OpenAPI в командах поначалу почти всегда возникает одна и та же путаница: фронтендеры воспринимают страницу со списком эндпоинтов исключительно как веб-справочник для чтения глазами. Получив ссылку на документацию, разработчик открывает вкладку в браузере, разворачивает цветные плашки запросов, всматривается в поля ответа и вручную перепечатывает interface User или параметры оплаты в редактор кода. Визуальную оболочку принимают за сам инструмент, хотя веб-страница — лишь витрина над машиночитаемым файлом контракта.

Пока этот контракт переносится в проект руками, фронтенд остаётся заложником чужого расписания: если бэкенд ещё не выкатил тестовый стенд, вёрстка и логика встают на паузу, а любое переименование поля на сервере вскрывается только при падении стейджинга. В разборе в канале Node.JS ru и подробной статье на Хабре инженер под ником itwillwork разложил по шагам, как превратить сырую схему OpenAPI в рабочий конвейер фронтенда. Меня в этом руководстве особенно зацепило то, как связка генератора типов, локального мок-сервера и патчинга схемы полностью отвязывает фронтенд от готовности бэкенда.

Контракт вместо справочника: как достать сырую схему из веб-документации

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

Логическая цепочка здесь прямая: если браузер рисует интерактивную таблицу методов в Swagger UI или ReDoc, значит, он только что сам скачал по сети исходный файл со схемой. Просить бэкендера скинуть документ в личку не нужно — достаточно открыть вкладку Network в панели разработчика (DevTools), обновить страницу и найти запрос к файлу .json, .yaml или .yml, где первой строчкой указана версия стандарта (openapi: 3.0.x или 3.1.x).

Посмотрим, как это меняет дело на практике. Допустим, твоя команда берёт в спринт интеграцию нового платёжного шлюза и профиля плательщика, но на бэкенде готов только ранний драфт ./schema/openapi.yaml, а тестового стенда не будет ещё неделю. Забрав этот файл в репозиторий, ты за 5 минут разворачиваешь из него строгие типы ответов и локальный сервер-заглушку, спокойно собирая UI с первого дня спринта.

Чистые типы без лишнего веса в бандле: как работает openapi-typescript

Первое звено такого пайплайна — автоматическое извлечение интерфейсов TypeScript напрямую из схемы. На современном стеке (Node.js 18+ и TypeScript 5+) ручное написание DTO-моделей теряет смысл: чем быстрее меняется API на старте продукта, тем выше риск пропустить изменившееся поле при ручной сверке.

Долгое время разработчиков отпугивали тяжёлые комбайны прошлых поколений вроде @openapitools/openapi-generator-cli, которые генерируют SDK для 50+ языков, но притаскивают в проект громоздкие классы и лишний рантайм-код. По-моему, куда аккуратнее задачу решает openapi-typescript. Он работает как чистый компилятор схем: читает локальный файл или URL спецификации OpenAPI 3.0/3.1 и переводит секции маршрутов (paths), операций (operations) и моделей (components) в плоский файл деклараций .d.ts без единого байта в итоговом JavaScript-бандле. Достаточно добавить в package.json вызов npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts, и любое изменение поля на сервере тут же подсветится компилятором tsc до коммита.

Связка типов с запросами и локальный мок-сервер за пять минут

Чтобы декларации .d.ts заработали в полную силу, сгенерированные структуры связывают с сетевым клиентом и направляют на локальный мок-сервер, пока реальный бэкенд платёжного шлюза ещё пишется:

  • Для нативного fetch в пару к генератору ставится легковесный клиент openapi-fetch весом около 6 КБ, принимающий интерфейс paths и выводящий типы маршрутов, параметров и ответов.
  • Для TanStack React Query инструмент Orval генерирует готовые хуки запросов, а для Redux Toolkit аналогичную задачу решает @rtk-query/codegen-openapi.
  • В прослойке BFF на Node.js и Express общие типы подключаются к контроллерам, а express-openapi-validator проверяет запросы и ответы по схеме в рантайме.

Соберём рабочий контур для нашего сценария: установим пакеты генерации и консольный мок-сервер Stoplight Prism, сгенерируем типы из ./schema/openapi.yaml, поднимем эмулятор API на порту 4010 и выполним типизированный запрос профиля пользователя:

// В терминале:
// npm install -D openapi-typescript @stoplight/prism-cli && npm install openapi-fetch
// npx openapi-typescript ./schema/openapi.yaml -o ./src/types/api.d.ts
// npx prism mock ./schema/openapi.yaml -p 4010

import createClient from 'openapi-fetch';
import type { paths } from './types/api';

const client = createClient<paths>({ baseUrl: 'http://localhost:4010' });

// Полный автокомплит эндпоинтов, параметров и тела ответа:
const { data, error } = await client.GET('/v1/users/{userId}', {
  params: { path: { userId: '123' } },
});

Передав интерфейс paths в createClient<paths>(), мы жёстко связали шаблон адреса '/v1/users/{userId}' с обязательным свойством params.path.userId. Если опечататься в URL или забыть передать идентификатор, сборка упадёт на этапе проверки типов, а в объектах data и error редактор сразу подскажет поля успешного ответа и ошибки.

На порту 4010 запрос встречает локальный процесс prism mock. Он читает ./schema/openapi.yaml, валидирует заголовки и параметры вызова и возвращает JSON-ответ по примерам из схемы. Важно учитывать границу применимости: Prism отдаёт статические или случайные данные без сохранения состояния между вызовами. Поэтому для многошаговых сценариев, где платёж меняет баланс при следующем запросе, поверх схемы подключают Service Worker через msw-auto-mock либо генерируют фикстуры утилитами openapi-sampler и json-schema-faker.

Когда контракт врёт: декларативный патчинг схемы через openapi-modifier

На практике почти каждая команда попадает в одну и ту же ловушку: спецификация от бэкенда редко бывает идеальной. При ручном написании YAML серверные разработчики допускают опечатки — пишут type: int вместо type: integer, format: datetime вместо date-time или забывают type: object у модели. А при автогенерации схемы из кода в неё попадают внутренние маршруты /internal/ и /private/ или конструкции, ломающие генератор.

Первый порыв — открыть скачанный openapi.yaml или api.d.ts и быстро поправить ошибку руками. Но такая заплатка живёт ровно до следующего обновления файла с сервера, когда все ручные правки затираются (почему нельзя править сгенерированные контракты вручную, я подробно показывал в разборе автогенерации типов из OpenAPI в связке Laravel и TypeScript). Обычные линтеры схем здесь тоже не выручат: они лишь укажут на ошибку в консоли, но не починят чужой файл.

Чтобы не ждать фиксов от бэкенда, itwillwork выстраивает перед кодогенерацией декларативный конвейер трансформации через утилиту openapi-modifier. В файле openapi-modifier.config.js задаётся цепочка правил (pipeline), которая при запуске npx openapi-modifier берёт ./schema/openapi.yaml и сохраняет исправленную копию ./schema/openapi.prepared.yaml:

  • Точечное исправление типов (patch-component-schema): правило с patchMethod: 'merge' находит дескриптор вроде User.id или Pet.id и заменяет ошибочное описание на { type: 'string', format: 'uuid' } (или правит int на integer), сохраняя остальные поля модели.
  • Добавление фич до релиза бэкенда (merge-openapi-spec и deepmerge): если для задачи JIRA-232 нужно сверстать экран, а эндпоинта в общей схеме ещё нет, правило merge-openapi-spec вливает черновик docs/feature-JIRA-232.yaml, а patchMethod: 'deepmerge' добавляет новое свойство в модель.
  • Очистка и контроль устаревания: правило filter-endpoints по регулярке /^\/internal\// вырезает служебные ручки, remove-unused-components удаляет повисшие схемы, а remove-deprecated и remove-parameter убирают устаревшие параметры, чтобы TypeScript сам подсветил вызовы, которые пора переписать.
Сборка без ручных правок

Свяжи подготовку контракта и генерацию типов в один скрипт package.json: сначала npx openapi-modifier прогоняет правила с комментариями номеров задач (например, JIRA-8752) и создаёт openapi.prepared.yaml, а следом npx openapi-typescript строит по нему api.d.ts. Когда бэкенд исправит опечатку на своей стороне, временное правило удаляется из конфига одной строкой.

В итоге связка из сырой схемы, мок-сервера Prism, декларативного патчинга через openapi-modifier и генератора openapi-typescript снимает блокировки в спринтах: фронтенд собирает рабочий интерфейс платёжного шлюза до готовности тестового стенда. А если захочешь посмотреть примеры для RTK Query, React Query и Express или забрать полную шпаргалку по правилам трансформации, загляни в оригинальную статью на Хабре.

Хочу подробный разборГолоса помогают выбрать, что разобрать подробно. За этот материал 0 голосов.
Источники · 3