# ✨ Написать OpenAPI-спеку руками

- **Тип:** feature
- **Категория:** Ядро
- **Зачем:** Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате
- **Теги:** goal:read-api, sprint:2026-08-04

Контракт читается машиной: по спеке генерируется клиент, и сгенерированный
клиент выполняет запрос к живому сервису.

**Решено владельцем 2026-08-04: спека пишется руками и она источник истины.**
Для API из горстки ручек это честнее вывода из кода — контракт проектируется, а
не фотографируется с того, что вышло: опечатка в имени поля иначе становится
частью спеки. Совпадает с тем, как в проекте уже устроен OpenSpec: спека
первична к коду. Плата названа — рукописная спека расходится с кодом молча, — и
именно поэтому проверка расхождения вынесена в
[отдельную задачу](openapi-gate-check.md), а не оставлена регламентом.

Заодно снимает вопрос, чем быть «схеме контракта API» из раздела самоописания:
ею и будет OpenAPI-документ, а не собственный формат.

Двигает строку «Завершения» цели: «Контракт чтения читается машиной».

## Критерии приёмки

- по спеке генерируется клиент, и он выполняет запрос к живому сервису — оракул:
  прогон генератора плюс запрос сгенерированным клиентом
- спека покрывает все маршруты, которые сервис действительно регистрирует —
  оракул: сверка перечня путей спеки с обходом роутера поднятого сервиса
  (`chi.Walk`)
- спека проходит валидатор OpenAPI 3.1 — оракул: прогон валидатора

## Рамки

Кода маршрутов не трогает: описывает то, что уже есть. `/stats` не описывается —
его ещё нет, и его добавит [своя задача](stats-endpoint.md).
