doc: промпт Соннету — улучшить Swagger/OpenAPI в polygon v0.4.0

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

@@ -0,0 +1,68 @@
+# Задача: улучшить 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 главных улучшений которые дадут максимальный эффект при минимуме правок.