av
3d24248075
- каждая запись каталога задач получила тип вместо тега kind: и префикса заголовка; секция роадмапа «Разработка» стала «Сопровождением», порядок секций канонический - поправлены протухшие факты: нереализованные маршруты Read API, MCP и `healthlog import`, словарь слоёв в инварианте, семантика гейта по покрытию диффа, периметр перестал дублировать security.md - замер слияния переведён с находки 49 на находку 54, заполнены Purpose спек storage и parsing
37 lines
2.7 KiB
Markdown
37 lines
2.7 KiB
Markdown
# ✨ Написать 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).
|