NestJS + OpenAPI: как сделать контракт API удобным для фронтенда и команды

•
Опубликовано
•
17 мин чтения

Текст написан с позиции июня 2024 года: так, как тема выглядела тогда, без технологий и событий, появившихся позже.

Хороший API-контракт почти никогда не рождается сам собой. Особенно в backend-проектах на NestJS, где очень легко обмануться приятной структурой фреймворка. Есть контроллеры, DTO, декораторы, валидация, Swagger UI, автогенерация документации — и все это создает успокаивающее ощущение, будто контракт уже “почти готов” просто по факту использования правильного стека. На практике это, конечно, не так. OpenAPI в NestJS способен либо стать очень полезным рабочим слоем между backend, frontend и командой в целом, либо превратиться в красивую, но слабо пригодную витрину, которая формально существует, а реально не помогает ни в разработке, ни в согласовании изменений.

Проблема обычно не в самом инструменте. У NestJS есть вполне зрелая интеграция с OpenAPI через @nestjs/swagger: можно генерировать спецификацию, описывать операции, модели, параметры, security-схемы, глобальные ответы, а также использовать CLI plugin, чтобы уменьшить бойлерплейт при описании DTO. Сам модуль Swagger/OpenAPI в NestJS уже давно умеет больше, чем просто “рисовать Swagger UI”. Но именно из-за этого команды часто начинают использовать его как декоративный слой, а не как реальный контракт. В итоге документация вроде бы есть, а фронтенд все равно уточняет в чате, что на самом деле вернет endpoint, какие поля бывают nullable, какие ошибки реально возможны и чем отличается один список от другого.

Самая вредная реакция на проблему контракта — услышать “у нас фронтенд жалуется на API” и решить, что надо добросить декораторов и тщательнее настроить Swagger UI. Это лечение симптома. Вопрос “как сделать контракт API удобным” намного важнее вопроса “как подключить SwaggerModule”. Подключить его несложно. Сложнее сделать так, чтобы OpenAPI-описание действительно совпадало с тем, как фронтенд будет потреблять API, а команда — поддерживать его месяцами без тихого расхождения между реальностью и документацией. Тут уже речь не про декораторы как таковые, а про качество архитектурных договоренностей. Что считается ресурсом? Как оформляются ошибки? Где проходит граница между DTO для входа и DTO для выхода? Насколько стабилен shape ответа? Что можно менять без боли, а что ломает клиентов? Пока на эти вопросы нет четких ответов, никакой NestJS-декоратор сам по себе не сделает контракт хорошим.

Зафиксируем сразу: хороший OpenAPI-контракт полезен не только фронтенду. Он полезен всей команде как способ нормализовать язык системы. Когда backend и frontend обсуждают не “примерно такой JSON”, а устойчиво описанный ответ с понятными полями, вариантами ошибок, типами параметров и предсказуемой схемой, уменьшается не только число багов, но и число архитектурных недоразумений. Современный фронтенд часто живет на code generation, typed clients, shared schemas и ожидании, что спецификация API — это уже не постфактум документация, а часть производственного контура. И тут важно не перепутать причину со следствием: стек NestJS + OpenAPI окупается не потому, что подключен, а потому, что им пользуются как контрактом.

Почему Swagger UI сам по себе еще не означает хороший контракт

Одна из самых частых ошибок в командах выглядит так: backend подключает SwaggerModule, настраивает базовый DocumentBuilder, получает красивую страницу с endpoint’ами и считает, что вопрос контракта закрыт. Формально спецификация есть. Но очень быстро выясняется, что между “документация существует” и “документация удобна” лежит довольно большая дистанция.

Неудобный контракт обычно узнается по нескольким симптомам. Во-первых, он описывает backend так, как его удобно было писать, а не так, как его удобно потреблять. Во-вторых, ответы слишком буквально повторяют внутреннюю persistence-модель и плохо совпадают с реальными UI-сценариями. В-третьих, документация молчит о том, что действительно важно: какие ошибки типичны, какие поля обязательны, где nullable допустим по-настоящему, как выглядит пустой результат, чем отличается “нет данных” от “нет доступа”. В-четвертых, backend использует OpenAPI-декораторы скорее для того, чтобы “заставить Swagger выглядеть прилично”, чем для того, чтобы выразить стабильный договор.

Дело не в том, что Swagger UI плох. Он очень хорош как окно в уже существующий контракт — и почти бесполезен как замена самому контракту. Если модель API плохо продумана, интерфейс документации только сделает это видимым. И это, кстати, полезный эффект. Потому что хорошая OpenAPI-практика начинается с признания: проблема не в отсутствии красивой страницы, а в отсутствии ясной формы общения между слоями системы.

Фронтенду нужен не “доступ к endpoint’ам”, а понятный shape данных

Backend-команды нередко мыслят OpenAPI в терминах отдельных маршрутов: вот метод, вот тело запроса, вот ответ. Для фронтенда это только часть картины. В реальном приложении важен не просто список endpoint’ов, а предсказуемость shape данных. Фронтенд-команда хочет понимать, как выглядит сущность в списке, как — в деталке, какие поля действительно гарантированы, какие бывают только в отдельных сценариях, как устроены связанные объекты, где возможен частичный ответ, что означает отсутствие поля и можно ли безопасно опираться на его наличие.

Именно здесь многие API-контракты начинают проседать. Backend описывает “технически валидный” ответ, но не выражает его как устойчивый продуктовый интерфейс. Например, список пользователей и карточка пользователя могут возвращать очень разные формы, хотя по смыслу frontend ожидает хотя бы часть общего контракта. Или в одном месте дата приходит строкой ISO, а в другом — как число, потому что так “исторически сложилось”. Или поле status в одном эндпоинте строка, в другом объект с метаданными. Все это можно задокументировать. Но если не приводить такие вещи к общей модели, спецификация будет лишь описывать хаос, а не устранять его.

Хороший контракт поэтому нужно строить не от маршрута, а от потребления. Какие представления сущности реально нужны фронтенду? Какие из них устойчивы? Где нужен list item DTO, где detail DTO, где compact DTO для вложенного использования? Чем раньше команда начинает мыслить так, тем полезнее становится OpenAPI.

DTO для входа и DTO для выхода не должны быть одной и той же сущностью

Это одна из тех тем, где экономия усилий почти всегда аукнется позже. Команды очень любят использовать одну и ту же class-модель в нескольких ролях сразу: для валидации входа, для документации, для response schema, а иногда еще и как внутреннее представление данных. На короткой дистанции это выглядит как разумное сокращение дублирования. На длинной — часто превращает контракт в спутанный компромисс между слоями системы.

Входной DTO и выходной DTO решают разные задачи. Вход описывает, что клиент может или должен прислать. Выход описывает, что система обещает вернуть. Эти две формы далеко не всегда симметричны. Более того, они часто не должны быть симметричны. Например, поле пароля на входе есть, а на выходе нет. Поля вычисленной статистики на выходе есть, а на входе быть не должно. Часто часть вложенных объектов в ответе уже денормализована или адаптирована под UI, тогда как вход остается более узким и транзакционным.

Когда команда смешивает эти роли, OpenAPI начинает отражать не ясный договор, а компромиссную форму, выросшую из удобства backend-кода. Для фронтенда это почти всегда хуже. Поэтому одна из лучших практик в NestJS + OpenAPI — относиться к response DTO как к самостоятельной части контракта, а не как к побочному продукту того, что уже есть для input validation.

Автогенерация помогает, но не заменяет явного моделирования

NestJS может автоматически многое вывести для OpenAPI-документа: он анализирует @Body(), @Query() и @Param() в route handlers, использует reflection и может строить модель документации на основе DTO. Но у reflection есть ограничения, и документация Nest прямо указывает, что свойства DTO либо нужно явно помечать через @ApiProperty(), либо использовать CLI plugin, который добавляет часть таких аннотаций на этапе компиляции. Это важный момент, потому что он напоминает: автоматическая генерация — это ускоритель, а не источник архитектурной истины.

Команда очень легко начинает ожидать от генерации слишком многого. Кажется, что если DTO описан и валидация есть, то спецификация “сама станет правильной”. Но OpenAPI — это не просто отражение TypeScript-класса. Это коммуникационный контракт. И многие важные вещи в нем не выводятся автоматически из одной только структуры полей: смысловые описания, корректные response-коды, варианты ошибок, security-ожидания, глобальные параметры, различие между несколькими представлениями одной сущности, ограничения на enum-значения в контексте конкретной операции.

Именно поэтому лучший подход — использовать генерацию как средство уменьшить ручной бойлерплейт, но не отказываться от явного проектирования. OpenAPI-документ становится хорошим не тогда, когда в нем “мало ручной работы”, а тогда, когда он ясно выражает реальный договор.

CLI plugin — полезный инструмент, но не повод перестать думать

CLI plugin в NestJS действительно полезен. Документация прямо говорит, что он существует для уменьшения бойлерплейта и помогает компенсировать ограничения metadata reflection, в частности вокруг свойств DTO и optional/required semantics. Для команд, у которых много DTO и много повторяющихся моделей, это очень практичное ускорение. Но именно здесь легко сделать неверный вывод: раз plugin подставляет многое сам, значит можно перестать уделять внимание форме контракта.

На практике plugin помогает только на одном уровне — уровне технической аннотации. Он не решает, как именно вы моделируете ответ. Не определяет, стоит ли вам возвращать массив с вложенным объектом или денормализованный список с pagination envelope. Не помогает договориться, какие коды ошибок должны быть общими по всей системе. Не отвечает на вопрос, не тащите ли вы persistence-модель наружу в ущерб фронтенду.

Поэтому к plugin лучше относиться как к хорошей механической помощи, но не как к смысловой автоматизации. Он делает меньше рутинной работы. Но качество контракта по-прежнему зависит от решений команды, а не от того, насколько аккуратно TypeScript-классы превратились в схему.

Ответы должны быть последовательными сильнее, чем “идеально RESTful”

Когда команды начинают проектировать API-контракт, очень часто спор быстро уходит в идеологию: насколько это REST, насколько правильно названы ресурсы, насколько “чисто” выглядит URL-модель. Все это имеет значение, но для фронтенда почти всегда важнее другая характеристика — последовательность. Если список сущностей в одном модуле завернут в items, total, page, а в другом приходит просто массив; если успешное удаление где-то возвращает тело, а где-то пустой ответ; если ошибки валидации в одном контроллере имеют один формат, а в другом — другой, никакая REST-эстетика уже не спасает UX разработки.

Хороший OpenAPI-контракт должен быть не только “теоретически правильным”, но и предсказуемым на уровне паттернов. Фронтенд-команда хочет знать: пагинация всегда выглядит так? Ошибки 401/403 описываются так? Bulk-операции возвращают такой envelope? Фильтры передаются именно этим способом? Сортировка именуется последовательно? Когда эти паттерны устойчивы, фронтенд начинает двигаться быстрее, typed clients становятся полезнее, а кодогенерация перестает быть источником локальных исключений.

Именно поэтому OpenAPI полезно проектировать как систему повторяющихся соглашений, а не как набор изолированных endpoint-описаний.

Ошибки — это тоже часть контракта, а не побочный шум

Очень многие API-документы прекрасно описывают happy path и почти ничего не делают для unhappy path. Это одна из самых неприятных привычек backend-команд. На уровне документации все выглядит гладко: вот 200, вот тело, вот DTO. Но в реальной жизни frontend чаще всего сталкивается не только с идеальным ответом. Он сталкивается с валидацией, отсутствием доступа, конфликтами, несуществующими ресурсами, ограничениями бизнес-логики, просроченными токенами, частично доступными операциями и массой других сценариев.

NestJS позволяет явно описывать ответы через @ApiResponse() и shorthand-декораторы вроде @ApiOkResponse(), @ApiCreatedResponse() и так далее. Но сам факт наличия этих декораторов еще не гарантирует, что команда действительно моделирует ошибки как часть контракта. Очень часто в коде есть один красивый @ApiOkResponse и полное молчание о том, как выглядит 400 или 409 в прикладных сценариях.

Между тем именно ошибки чаще всего влияют на фронтенд-архитектуру: что показывать пользователю, когда ретраить, где можно различить “не найдено” и “запрещено”, как строить формы, как маппить поле ошибки и т.д. Если контракт в этой зоне слабый, UI обрастает guesswork-логикой. Поэтому хорошая OpenAPI-практика почти всегда включает стандартизацию error shape и явное описание типовых response scenarios.

Глобальные правила стоит поднимать в общий уровень документа

Одно из сильных мест интеграции OpenAPI в NestJS — возможность задавать общие параметры, общие ответы и даже несколько спецификаций. Это важные возможности именно для удобства команды, а не только для “полноты Swagger UI”. Когда система действительно живет как платформа, в ней почти всегда есть сквозные вещи: tenant header, language header, auth bearer token, типовые 401/403/500 ответы, единые схемы безопасности, раздельные зоны документации для разных модулей или аудиторий API. NestJS позволяет часть этого поднять на уровень DocumentBuilder и общей сборки спецификации.

Это особенно полезно по двум причинам. Во-первых, уменьшается бойлерплейт и риск, что в одном контроллере нужный общий параметр задокументирован, а в другом забыт. Во-вторых, OpenAPI начинает выглядеть как единый продуктовый документ, а не как склейка отдельных контроллеров, где каждый сам за себя. Для фронтенда это сильно повышает предсказуемость. Для backend-команды — снижает случайную разнородность между модулями.

Вообще, один из лучших признаков зрелого API-контракта — когда общие правила действительно описаны как общие, а не повторяются вручную там, где кто-то вспомнил.

Контракт должен быть удобен не только людям, но и генераторам клиентов

OpenAPI почти всегда живет уже не в одиночку. Очень часто спецификация становится входом для codegen: typed API clients, SDK, frontend hooks, схемы валидации, mock servers, contract tests. И это очень сильно меняет требования к качеству документа. Дело не в моде на кодогенерацию, а в смене читателя: когда OpenAPI нужен только человеку, часть неточностей еще можно простить и “договорить голосом”; когда его начинают читать машины, любая двусмысленность быстро становится дорогой.

Если тип поля ведет себя нестабильно, если один и тот же ответ моделируется по-разному в разных местах, если nullable и optional перепутаны, если enum по факту шире, чем описано, если ошибки не имеют устойчивой схемы, фронтенд-команда очень быстро перестает доверять генерации и возвращается к рукописным типам. А это уже поражение контракта как производственного инструмента.

Именно поэтому удобный OpenAPI-контракт должен проектироваться с учетом того, что его будут не только читать в Swagger UI, но и использовать как источник typed truth. Чем раньше backend начинает об этом думать, тем меньше потом будет “маленьких исключений”, которые разрушат доверие к спецификации.

Несколько спецификаций — это не экзотика, а нормальный способ не смешивать аудитории

Очень полезная возможность в NestJS — поддержка нескольких OpenAPI-спецификаций через модульный подход и опцию include при создании документа. Это может выглядеть как продвинутая фича “на будущее”, но на практике она часто оказывается очень зрелым решением. У многих систем есть разные аудитории API: публичный frontend, внутренняя админка, партнерский доступ, внутренние сервисные маршруты, support-интерфейсы. Когда все это смешивается в одну гигантскую Swagger-страницу, документация становится не полезнее, а шумнее.

Разделение спецификаций помогает не только UX документации. Оно помогает точнее мыслить контракт. У каждой аудитории появляются свои правила, свои security-модели, свои ресурсы и свои expectations. Фронтенду в этом случае не приходится пробираться через десятки не относящихся к нему endpoint’ов, а backend-команда получает более чистую модульную картину системы.

Это, кстати, хороший пример того, как “удобный контракт” — это не только вопрос формы поля, но и вопрос того, насколько сам документ соответствует реальной карте потребителей.

Схема должна следовать за exception policy, а не спорить с ней

В NestJS есть встроенный exception layer и стандартное поведение для необработанных ошибок. Из коробки неизвестные ошибки превращаются в JSON с statusCode и сообщением про internal server error. Это важное напоминание: если команда не определила свою собственную error policy и не синхронизировала ее с OpenAPI, документация начнет либо молчать о реальности, либо фантазировать о порядке, которого в рантайме нет.

Хорошая практика здесь довольно простая. Сначала вы определяете реальную политику исключений: какие ошибки являются доменными, какие транспортными, какие коды используете последовательно, как выглядит validation error, как выглядит business conflict, где хранится machine-readable code, нужен ли correlation id и так далее. И только после этого OpenAPI отражает эту модель. Не наоборот.

Это важный момент, потому что документация не должна быть отдельным миром. Если она описывает не ту форму ошибки, которую реально вернет backend, фронтенд снова оказывается в положении, где спецификация теоретически полезна, но практически ненадежна.

Хороший контракт начинается с product-level use cases, а не с сущностей базы

Одна из самых вредных привычек backend-команд — строить OpenAPI почти прямо из persistence-модели. Есть таблица users — значит будет user controller. Есть orders — значит order controller. Ответы будут похожи на то, как сущности живут в базе, а потом frontend “как-нибудь разберется”. Такая схема удобна для старта, но она редко дает хороший контракт.

Фронтенду почти никогда не нужен “просто объект из базы”. Ему нужен сценарий: список пользователей для таблицы, карточка пользователя с ролями, быстрый summary для sidebar, детальный заказ с расчетными полями, компактный список для выпадающего селекта и так далее. Все это часто разные формы одной и той же сущности. Если контракт проектируется от базы, а не от use case, OpenAPI получается технически валидным, но продуктово неудобным.

Гораздо полезнее начинать с вопроса: какой именно экран или поток потребляет этот endpoint? Тогда контракт естественнее становится удобным для фронтенда. И уже потом можно решать, как именно backend собирает этот ответ. Это чуть менее “чистая” абстракция в духе CRUD-мира, но намного более полезная для реальной команды.

За идеальный контракт тоже приходится платить — лишними DTO и дисциплиной

Здесь важно не свалиться в другую крайность и не превратить контракт в самоцель. У всего описанного выше есть цена, и о ней честнее сказать прямо. Раздельные input и output DTO, отдельные представления сущности под разные экраны, стандартизованный error shape, вынесенные в общий уровень параметры — это не бесплатно. Это больше классов, больше точек, где описание может разойтись с кодом, больше дисциплины при каждом изменении. Команда, которая бросится строить “идеальный контракт” на стартапном MVP с тремя эндпоинтами и одним потребителем, скорее всего, заплатит за зрелость, которая ей пока не нужна.

Поэтому правильная формула не “всегда максимально строго”, а “строго там, где контракт действительно живет как граница между командами и инструментами”. Если API читает только один фронтенд, написанный теми же людьми, и спецификация никуда не уходит в codegen, часть формальностей можно отложить без вреда. Если же контракт пересекает границу команд, питает typed clients или открыт наружу — экономия на форме почти наверняка вернется расхождениями и потерей доверия к документу. Это не вопрос вкуса, а вопрос того, сколько у контракта реальных читателей и насколько дорого им ошибиться.

Итог

NestJS + OpenAPI сами по себе уже дают очень много: генерацию спецификации, SwaggerModule, декораторы для операций и ответов, security-описания, mapped types, CLI plugin для уменьшения бойлерплейта, глобальные параметры и ответы, а также возможность собирать несколько спецификаций по модулям. Но весь этот стек становится по-настоящему полезным только тогда, когда команда воспринимает OpenAPI не как декоративную документацию, а как рабочий контракт между backend, frontend и самим процессом разработки.

Удобный контракт — это не просто “все endpoint’ы описаны”. Это значит, что формы данных проектируются от реального потребления, input и output DTO не смешиваются без необходимости, ошибки являются частью документа наравне с happy path, общие правила действительно вынесены в общий уровень, а сама спецификация достаточно последовательна, чтобы на нее можно было опереться и человеку, и code generator’у. В такой модели NestJS становится не генератором Swagger-страницы, а хорошим фреймворком для дисциплинированного контракта.

Если сформулировать главный практический вывод совсем прямо, то он будет таким: хороший NestJS + OpenAPI контракт рождается не там, где вы просто добавили @ApiProperty() и увидели красивый Swagger UI, а там, где backend начал моделировать ответы, ошибки и общие правила так, как их реально будут использовать фронтенд и команда. SwaggerModule, декораторы и CLI plugin — сильные инструменты, но они вторичны по отношению к самой договоренности и не способны ее заменить.

Автор

Senior Principal JavaScript Developer, Tech Lead. Пишет о React, TypeScript, React Native, архитектуре фронтенда и бэкенда и о том, как AI меняет работу разработчика.

Обновлено

Читайте также