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.)
• Не усложнять — полигон это мок, не прод
• Не предлагать автогенерацию из кода через декораторы

Дополнительные вопросы

requestInterceptor и X-Mock-Auth

Сейчас swagger.html добавляет только Authorization: Bearer через requestInterceptor. Но _mock/* эндпоинты проверяют заголовок X-Mock-Auth, а не Authorization. Как правильно дописать requestInterceptor чтобы оба механизма работали:

• Authorization: Bearer <token> — для всех эндпоинтов (если включена глобальная auth)
• X-Mock-Auth: <token> — только для _mock/*

docExpansion

Какое значение docExpansion оптимально для Swagger UI 5?

• "list" — раскрыты только названия тегов (средний вариант)
• "none" — всё свёрнуто (минимализм)
• "full" — все эндпоинты раскрыты (но может быть перегружено)

Учитывая что есть 5 тегов (services, instances, operations, health, mock) и ~17 эндпоинтов.

Примеры ответов (examples)

В каких схемах стоит добавить example чтобы Try it out был максимально полезен? Например:

• Instance с реальными данными (instanceUid, serviceId, status, state.params, state.out)
• CfsParam с valueList (чтобы было видно как выглядят enum-параметры)
• Operation до run (dtStart=null, dtFinish=null) и после run (всё заполнено)

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

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

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

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

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

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

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

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