← назад к разделу

API-first начинается с договоренности о ресурсах, полях, статусах и ошибках. Контроллеры появляются после того, как стороны могут проверить контракт вместе, а не после того, как фронтенд уже написан под выдуманный ответ.

Контракт как общий источник

OpenAPI-файл описывает пути, схемы DTO, коды ответов и примеры. Он позволяет бэкенду и фронтенду работать параллельно: один поднимает мок по спецификации, другой проверяет соответствие реализации.

Порядок выглядит так:

  1. Описать ресурс и операции с пользовательскими сценариями.
  2. Согласовать ошибки, включая тело application/problem+json.
  3. Зафиксировать OpenAPI в репозитории.
  4. Сгенерировать мок и клиента или написать их вручную по контракту.
  5. Проверять реализацию и изменения контракта в CI.

Генерация не заменяет проектирование. Она лишь уменьшает расхождение между текстом договора и повторяющимся кодом.

От контракта к NestJS

NestJS умеет формировать OpenAPI из декораторов через @nestjs/swagger. Это code-first направление, полезное для публикации текущего API. При API-first источником остается исходная спецификация, а не сгенерированный документ.

Контроллер и DTO сверяют с ней:

@Post('/orders')
@HttpCode(201)
create(@Body() command: CreateOrderDto): OrderView {
  return this.orders.create(command);
}

Путь, 201 и OrderView должны совпадать со спецификацией. Если декораторы говорят одно, а контракт другое, нужна явная правка контракта и миграционная политика, а не молчаливый дрейф.

Мок и проверка реализации

По OpenAPI поднимают мок-сервер с примерами ответов. Фронтенд начинает интеграцию до готовности NestJS. После появления реализации те же вызовы выполняют уже против нее.

Контрактная проверка отвечает на два вопроса:

  • принимает ли сервер запросы по схеме и возвращает ли документированные статусы;
  • не исчезли ли поля и не появились ли неожиданные, если whitelist и forbidNonWhitelisted настроены иначе, чем контракт.

ValidationPipe помогает проверять вход, но сам по себе не доказывает соответствие ответа. Его проверяют отдельными схемами или контрактными тестами.

Изменения без неявного дрейфта

Новое необязательное поле обратно совместимо. Удаление поля, изменение его типа или смысла кода ошибки - уже нет. Такие изменения проходят через версию, уведомление потребителей и период совместимости.

OpenAPI не должен быть красивым PDF для чтения. Это исполняемый договор с примерами и проверками, который обновляют вместе с кодом в одном pull request.

Коротко

  • API-first фиксирует контракт до контроллера.
  • OpenAPI позволяет поднять мок и работать параллельно.
  • Code-first документация из NestJS не заменяет исходную спецификацию.
  • Запрос и ответ проверяют по схеме отдельно.
  • Изменение контракта версионируют и проверяют в CI.

Что почитать дальше