av
d79189be18
- беклог и план переехали в docs/tasks (38 задач, 11 целей), слаги переименованы с транслита на английские, 85 ссылок поправлены - conventions.md разобран в docs/conventions/, local-research.md — в docs/research/, review-journal.md — в docs/review.md с разделом настройки конвейера; заведены security.md, adr/ и .pm.json - шаг docs.py check добавлен в task gate; поведение в architecture.md помечено девятью маркерами долга, database.md получил настройки с числовым значением
1.9 KiB
OpenAPI-спека и Swagger UI
Секция: ядро · Хук: Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате · Теги: goal:read-api
Потребителей три, и один из них — агент, который читает контракт машиной. Пересказывать форму ответа в чате не годится, а самоописание из плана покрывает только содержимое метрик; форма конверта, коды ответов и параметры запроса — это OpenAPI.
Заодно снимает вопрос, чем быть «схеме контракта API» из раздела самоописания: ею и будет OpenAPI-документ, а не собственный формат.
Шаги:
- спека OpenAPI 3.1 на приём, каталог, точки, тренировки, записи,
/stats; - Swagger UI на отдельном пути, отдаётся самим сервисом (без внешних CDN — он должен работать в локальной сети без интернета);
- проверка актуальности спеки в гейте: контракт разъезжается молча.
Готово, когда по спеке можно сгенерировать клиент, а Swagger UI открывается локально и выполняет запрос к живому сервису.
Развилка на решение: спека пишется руками как источник истины или выводится из кода. Для маленького API рукописная спека честнее — но это стоит обсудить.