feat: Swagger UI + OpenAPI 3.1.0 спека (v0.4.0)

- /swagger — Swagger UI (CDN, без pip-зависимостей)
- /api/v1/svc/openapi.json — динамическая OpenAPI 3.1.0 спека
- Nubes-брендированный topbar (лого + версия)
- Bearer-токен предзаполняется автоматически
- 17 эндпоинтов с полными схемами, примерами, описаниями
- Ссылка «Swagger» на главной странице

site/routes/root.py

@@ -1,8 +1,9 @@
 """
-routes/root.py — корневые эндпоинты (/health, /).
+routes/root.py — корневые эндпоинты (/health, /, /swagger).
 
 Blueprint "root" регистрируется в app.py БЕЗ url_prefix.
-Отвечает за healthcheck (для Nubes) и HTML-страницу с информацией о сервисе.
+Отвечает за healthcheck (для Nubes), HTML-страницу с информацией о сервисе,
+и страницу Swagger UI.
 """
 
 import os
@@ -14,6 +15,12 @@ import config.loader as _cfg
 # Версия — из config/loader.py (единый источник правды)
 VERSION = _cfg.VERSION
 
+# Токен для авторизации в Swagger UI (предзаполняется)
+_MOCK_AUTH_TOKEN = os.getenv("MOCK_AUTH_TOKEN", "test-token-123")
+
+# URL для OpenAPI-спеке (сервер)
+_POLYGON_ENDPOINT = os.getenv("POLYGON_ENDPOINT", "https://polygon.pythonk8s.dev.nubes.ru")
+
 # Blueprint без префикса — роуты /health и / будут на корне домена
 bp = Blueprint("root", __name__)
 
@@ -52,9 +59,6 @@ def index():
             "has_out": bool(svc.get("stateOut")),
         })
 
-    # URL для примеров — из переменной окружения или автоопределение
-    endpoint = os.getenv("POLYGON_ENDPOINT", "https://polygon.pythonk8s.dev.nubes.ru")
-
     return render_template(
         "index.html",
         version=_cfg.VERSION,
@@ -62,5 +66,20 @@ def index():
         inst_count=inst_count,
         delay=_cfg.DELAY,
         svc_list=svc_list,
-        endpoint=endpoint,
+        endpoint=_POLYGON_ENDPOINT,
+    )
+
+
+@bp.route("/swagger")
+def swagger():
+    """Swagger UI — интерактивная документация API.
+
+    Загружает Swagger UI с CDN, указывает на /api/v1/svc/openapi.json.
+    Токен авторизации предзаполняется автоматически (MOCK_AUTH_TOKEN).
+    """
+    return render_template(
+        "swagger.html",
+        version=_cfg.VERSION,
+        openapi_url="/api/v1/svc/openapi.json",
+        auth_token=_MOCK_AUTH_TOKEN,
     )