av
d33f37249c
- роадмап отвечает «что умеет и чего не умеет»: PLAN.md → ROADMAP.md, четыре канонические секции, достигнутые звенья строками в «Готово», цели переформулированы возможностями приложения - задачи: род работы и «Затрагивает» набору спринта, 34 заголовка в форму действия, «Завершение» целей перечнями со ссылкой из каждой задачи - вычитка проходами task-form и doc-wording, починены протухшие факты в README, паспорте и review.md
2.7 KiB
Написать OpenAPI-спеку руками
- Секция: Ядро
- Зачем: Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате
- Теги: goal:read-api, sprint:2026-08-04
Контракт читается машиной: по спеке генерируется клиент, и сгенерированный клиент выполняет запрос к живому сервису.
Решено владельцем 2026-08-04: спека пишется руками и она источник истины. Для API из горстки ручек это честнее вывода из кода — контракт проектируется, а не фотографируется с того, что вышло: опечатка в имени поля иначе становится частью спеки. Совпадает с тем, как в проекте уже устроен OpenSpec: спека первична к коду. Плата названа — рукописная спека расходится с кодом молча, — и именно поэтому проверка расхождения вынесена в отдельную задачу, а не оставлена регламентом.
Заодно снимает вопрос, чем быть «схеме контракта API» из раздела самоописания: ею и будет OpenAPI-документ, а не собственный формат.
Двигает строку «Завершения» цели: «Контракт чтения читается машиной».
Критерии приёмки
- по спеке генерируется клиент, и он выполняет запрос к живому сервису — оракул: прогон генератора плюс запрос сгенерированным клиентом
- спека покрывает все маршруты, которые сервис действительно регистрирует —
оракул: сверка перечня путей спеки с обходом роутера поднятого сервиса
(
chi.Walk) - спека проходит валидатор OpenAPI 3.1 — оракул: прогон валидатора
Рамки
Кода маршрутов не трогает: описывает то, что уже есть. /stats не описывается —
его ещё нет, и его добавит своя задача.