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