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

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

- Статус документа: working reference
- Актуально на: 30 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при закрытии response gaps, обновлении OpenAPI coverage или смене contract workflow
- Область применения: операционный список оставшихся OpenAPI response gaps для `qadam-core`
- Связанные документы:
  - [Карта API-маршрутов](./api-routes.md)
  - [API conventions](./api-conventions.md)
  - [Roadmap](../project/roadmap.md)
  - [Execution checkpoints](../project/execution-checkpoints.md)
  - [Change Log для frontend-команды](../frontend/frontend-change-log.md)

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

Этот документ фиксирует состояние 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:

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

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

```ts
@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`.

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

- [roadmap.md](../project/roadmap.md)
- [execution-checkpoints.md](../project/execution-checkpoints.md)
- [frontend-change-log.md](../frontend/frontend-change-log.md), если пакет влияет на frontend handoff