From 9fb21a40a86219c87db582ab4d0ff1dd89fcd2f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Sat, 1 Aug 2026 19:11:01 +0400
Subject: [PATCH] =?UTF-8?q?doc:=20=D0=BF=D1=80=D0=BE=D0=BC=D0=BF=D1=82=20?=
 =?UTF-8?q?=D0=A1=D0=BE=D0=BD=D0=BD=D0=B5=D1=82=D1=83=20=E2=80=94=20=D1=83?=
 =?UTF-8?q?=D0=BB=D1=83=D1=87=D1=88=D0=B8=D1=82=D1=8C=20Swagger/OpenAPI=20?=
 =?UTF-8?q?=D0=B2=20polygon=20v0.4.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 polygon-docs/sonnet-swagger-review-prompt.md | 68 ++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 polygon-docs/sonnet-swagger-review-prompt.md

diff --git a/polygon-docs/sonnet-swagger-review-prompt.md b/polygon-docs/sonnet-swagger-review-prompt.md
new file mode 100644
index 0000000..a65b34c
--- /dev/null
+++ b/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 главных улучшений которые дадут максимальный эффект при минимуме правок.