Qadam Roadmap
← Назад к библиотеке
проектdocs/architecture/openapi-gaps.md

OpenAPI gaps: недостающие response schemas

Обновлён 1 апр. 2026 г., 12:41 · 0 комментариев

ИсходникСкачать

OpenAPI gaps: недостающие response schemas

Паспорт документа

  • Статус документа: working reference
  • Актуально на: 30 марта 2026 года
  • Владелец: backend/platform-команда
  • Пересмотр: при закрытии response gaps, обновлении OpenAPI coverage или смене contract workflow
  • Область применения: операционный список оставшихся OpenAPI response gaps для qadam-core
  • Связанные документы:

Цель документа

Этот документ фиксирует состояние frontend-значимых endpoint'ов, у которых в OpenAPI отсутствовало полноценное описание response body. По состоянию на 30 марта 2026 года активный backlog этого класса закрыт полностью; документ сохраняется как контрольная точка и журнал закрытия contract gaps.

Что уже закрыто

  • Buyer profile response schemas уже публикуются в OpenAPI и больше не входят в активный backlog gaps.
  • Seller profile response schemas уже публикуются в OpenAPI и больше не входят в активный backlog gaps.
  • Auth auxiliary flows уже публикуют response schemas в OpenAPI и больше не входят в активный backlog gaps.
  • Staff уже публикует response schemas в OpenAPI и больше не входит в активный backlog gaps.
  • Reference data, включая публичный /api/v1/subjects, уже публикует response schemas в OpenAPI и больше не входит в активный backlog gaps.
  • Seller Items уже публикует response schemas в OpenAPI и больше не входит в активный backlog gaps.
  • Admin Dashboard уже публикует response schemas в OpenAPI и больше не входит в активный backlog gaps.
  • Admin Moderation уже публикует response schemas в OpenAPI и больше не входит в активный backlog gaps.

Правило счёта gaps

  • В этот backlog входят только те 2xx-ответы, где frontend ожидает response body, а OpenAPI не публикует content.
  • 204 No Content маршруты не считаются активным blocker backlog, даже если их ещё стоит позже оформить через @ApiNoContentResponse.
  • По состоянию на 30 марта 2026 года активный backlog составляет 0 endpoint'ов.

Как исправить

На каждом контроллере/методе добавить декоратор с описанием response body:

@ApiOkResponse({ description: '...', type: SomeResponseDto })

Для массивов:

@ApiOkResponse({ description: '...', type: [SubjectDto] })

После этого:

  1. pnpm export:openapi
  2. передать обновлённый openapi.json в web
  3. прогнать codegen и убрать ручные transport-типы

Активный backlog

На 30 марта 2026 года активных frontend-значимых response gaps в OpenAPI больше нет.

Закрытый пакет 30 марта 2026 года дополнительно завершил:

  • Seller Items (Dashboard)
  • Admin Dashboard
  • Admin Moderation

Итог

Активный backlog этого документа на 30 марта 2026 года составляет 0 frontend-значимых endpoint'ов.

Отдельно от этого backlog в API остаются 2 delete-маршрута с 204 No Content, которые не считаются blocker'ом для generated contract layer, но позже должны быть нормально оформлены через @ApiNoContentResponse.

Закрытие этого списка должно обновлять: