avandClaude Opus 5
a53d0f0f2f
49 файлов, миграция сделана командой tasks.py check --fix — той самой, ради которой в скрипте оставлена читаемость старой формы. Побочно тот же прогон проставил тег decomposed целям, у которых есть задачи: это его штатная работа. check после миграции зелёный, индексы согласованы. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
26 lines
1.9 KiB
Markdown
26 lines
1.9 KiB
Markdown
# OpenAPI-спека и Swagger UI
|
|
|
|
- **Секция:** ядро
|
|
- **Зачем:** Потребителей три и один из них агент — контракт должен читаться машиной, а не пересказываться в чате
|
|
- **Теги:** goal:read-api
|
|
|
|
Потребителей три, и один из них — агент, который читает контракт машиной.
|
|
Пересказывать форму ответа в чате не годится, а самоописание из плана покрывает
|
|
только **содержимое** метрик; форма конверта, коды ответов и параметры запроса —
|
|
это OpenAPI.
|
|
|
|
Заодно снимает вопрос, чем быть «схеме контракта API» из раздела самоописания:
|
|
ею и будет OpenAPI-документ, а не собственный формат.
|
|
|
|
Шаги:
|
|
- спека OpenAPI 3.1 на приём, каталог, точки, тренировки, записи, `/stats`;
|
|
- Swagger UI на отдельном пути, отдаётся самим сервисом (без внешних CDN —
|
|
он должен работать в локальной сети без интернета);
|
|
- проверка актуальности спеки в гейте: контракт разъезжается молча.
|
|
|
|
Готово, когда по спеке можно сгенерировать клиент, а Swagger UI открывается
|
|
локально и выполняет запрос к живому сервису.
|
|
|
|
Развилка на решение: спека пишется руками как источник истины или выводится из
|
|
кода. Для маленького API рукописная спека честнее — но это стоит обсудить.
|