# OpenAPI-спека и Swagger UI

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

Потребителей три, и один из них — агент, который читает контракт машиной.
Пересказывать форму ответа в чате не годится, а самоописание из плана покрывает
только **содержимое** метрик; форма конверта, коды ответов и параметры запроса —
это OpenAPI.

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

Шаги:
- спека OpenAPI 3.1 на приём, каталог, точки, тренировки, записи, `/stats`;
- Swagger UI на отдельном пути, отдаётся самим сервисом (без внешних CDN —
  он должен работать в локальной сети без интернета);
- проверка актуальности спеки в гейте: контракт разъезжается молча.

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

Готово, когда по спеке можно сгенерировать клиент, а Swagger UI открывается
локально и выполняет запрос к живому сервису.

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

- по спеке генерируется клиент, и сгенерированный клиент выполняет запрос к
  живому сервису — оракул: прогон генератора плюс запрос сгенерированным
  клиентом
- Swagger UI открывается и выполняет запрос **без внешней сети** — оракул:
  запуск с отключённым интернетом
- маршрут, разошедшийся со спекой, красит гейт — оракул: намеренно
  рассогласованный маршрут в прогоне гейта
- спека покрывает приём, каталог, точки, тренировки, записи и `/stats` —
  оракул: сверка перечня путей спеки с таблицей маршрутов в `architecture.md`

## Рамки

Схема не трогается, данные только читаются, сервис перезапускается. Берётся
после того, как маршруты чтения существуют: спека рукописная, но описывать
нечего, пока конверт не задан.