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