Вокруг 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 или забрать полную шпаргалку по правилам трансформации, загляни в оригинальную статью на Хабре.

![Node.JS [ru]](/api/digests/it_development/daily/20261112/assets/sources/we-use-js.jpg?v=96d603ea907a603e2476230869b24b042f87006317785f577b52227c3db5cc47)


