autotest/polygon-docs/sonnet-swagger-review-prompt.md

Задача: улучшить Swagger/OpenAPI в Polygon

Адресат: Claude Sonnet 4.6 (новый чат) ⛔ ОТВЕТ — ТОЛЬКО В ЧАТ. Не редактировать файлы.

---

Контекст

Polygon (v0.4.0) — эмулятор REST API облачной платформы Nubes. Задеплоен на polygon.pythonk8s.dev.nubes.ru. 17 эндпоинтов, 37 сервисов.

Недавно добавлен Swagger UI (/swagger) + OpenAPI 3.1.0 спека (/api/v1/svc/openapi.json). Сделано наспех — нужно улучшить.

Текущая реализация

• site/routes/openapi.py — динамическая OpenAPI 3.1.0 спека (~500 строк Python)
• site/templates/swagger.html — Swagger UI 5 c CDN (~120 строк HTML+JS)
• site/routes/root.py — роут /swagger → render_template
• Токен авторизации предзаполняется (test-token-123)
• Nubes-брендированный topbar (лого + версия)

Что нужно от тебя

1. Анализ текущего состояния

Найди проблемы и недочёты:

• Где спека не соответствует реальному поведению API?
• Где схемы неполные или неточные?
• Где Swagger UI неудобен (лишние эндпоинты, плохие группировки, запутанная навигация)?
• Где есть баги (неправильные методы, статус-коды, форматы)?

2. Решения

Для каждой проблемы — конкретное исправление. Покажи:

• Что поменять (файл, строка, фрагмент кода)
• Почему это улучшит (пользовательский опыт, точность, простота)
• Приоритет (обязательно / желательно / косметика)

3. Best practices

Научи как правильно:

• Группировать эндпоинты (tags) чтобы было логично
• Описывать схемы чтобы они были полезны в «Try it out»
• Скрывать служебные эндпоинты (_mock/* — нужны только для тестов)
• Писать summary/description на русском, коротко и по делу
• Обрабатывать авторизацию в Swagger UI чтобы работало из коробки

Что НЕ надо

• Не предлагать переписывать всё с нуля
• Не добавлять новые pip-зависимости (Flask-RESTX, flask-swagger-ui, etc.)
• Не усложнять — полигон это мок, не прод
• Не предлагать автогенерацию из кода через декораторы

Формат ответа

Сгруппируй находки так:

🔴 Баги (не работает / неверно)

🟡 Удобство (путает, неудобно)

🔵 Косметика (можно лучше)

📖 Best practices (как правильно)

Для каждой находки: файл, проблема, решение, приоритет.

В конце — 3-5 главных улучшений которые дадут максимальный эффект при минимуме правок.