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