av
79331ac670
- цель parsing-and-storage закрыта по своему критерию; незакрываемый остаток (новые формы от источника, ручные секции задним числом) переехал в тему parsing-completeness - цель mcp поглощена целью read-api, переименованной в «Чтение данных клиентами»: адаптер — последний шаг того же направления, а не своё - read-api-points разложена на конверт с точками, свёртку по сетке и тренировки с записями; спринт 2026-08-04 набран пятью задачами
3.7 KiB
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
Рамки
Схема не трогается, данные только читаются, сервис перезапускается. Берётся после того, как маршруты чтения существуют: спека рукописная, но описывать нечего, пока конверт не задан.