Merge pull request #523 from Fr1ngg/bedolaga/-scalar-redoc-api

Replace ReDoc with Scalar API reference
2025-09-28 04:24:32 +03:00
parent e3e6428d2a 37ac3e7a81
commit b4dc9f1970
4 changed files with 29 additions and 5 deletions
@@ -980,11 +980,11 @@ class Settings(BaseSettings):
        if self.WEB_API_DOCS_ENABLED:
            return {
                "docs_url": "/docs",
-                "redoc_url": "/redoc",
+                "scalar_url": "/scalar",
                "openapi_url": "/openapi.json",
            }

-        return {"docs_url": None, "redoc_url": None, "openapi_url": None}
+        return {"docs_url": None, "scalar_url": None, "openapi_url": None}

    def get_support_system_mode(self) -> str:
        mode = (self.SUPPORT_SYSTEM_MODE or "both").strip().lower()
@@ -2,6 +2,7 @@ from __future__ import annotations

 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse

 from app.config import settings

@@ -18,6 +19,8 @@ from .routes import (
    users,
 )

+from .docs import build_scalar_docs_html
+

 def create_web_api_app() -> FastAPI:
    docs_config = settings.get_web_api_docs_config()
@@ -26,7 +29,7 @@ def create_web_api_app() -> FastAPI:
        title=settings.WEB_API_TITLE,
        version=settings.WEB_API_VERSION,
        docs_url=docs_config.get("docs_url"),
-        redoc_url=docs_config.get("redoc_url"),
+        redoc_url=None,
        openapi_url=docs_config.get("openapi_url"),
        swagger_ui_parameters={"persistAuthorization": True},
    )
@@ -53,4 +56,15 @@ def create_web_api_app() -> FastAPI:
    app.include_router(promo_groups.router, prefix="/promo-groups", tags=["promo-groups"])
    app.include_router(tokens.router, prefix="/tokens", tags=["auth"])

+    scalar_url = docs_config.get("scalar_url")
+    if scalar_url and app.openapi_url:
+
+        @app.get(scalar_url, include_in_schema=False)
+        async def scalar_docs() -> HTMLResponse:
+            html_content = build_scalar_docs_html(
+                title=settings.WEB_API_TITLE,
+                openapi_url=app.openapi_url,
+            )
+            return HTMLResponse(content=html_content)
+
    return app
@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+import html
+
+
+def build_scalar_docs_html(*, title: str, openapi_url: str, theme: str = "modern") -> str:
+    escaped_title = html.escape(title)
+    escaped_openapi_url = html.escape(openapi_url)
+    escaped_theme = html.escape(theme)
+    return f"""<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n    <title>{escaped_title} API Reference</title>\n    <script src=\"https://cdn.jsdelivr.net/npm/@scalar/api-reference\"></script>\n    <style>\n      html, body {{\n        height: 100%;\n      }}\n      body {{\n        margin: 0;\n      }}\n      scalar-api-reference {{\n        height: 100%;\n      }}\n    </style>\n  </head>\n  <body>\n    <script>\n      const reference = document.createElement('scalar-api-reference');\n      reference.configuration = {{\n        spec: {{\n          url: '{escaped_openapi_url}'\n        }},\n        theme: '{escaped_theme}'\n      }};\n      document.body.appendChild(reference);\n    </script>\n  </body>\n</html>\n"""
@@ -34,7 +34,7 @@ API разворачивается вместе с ботом, использу
 Чтобы открыть интерфейс Swagger UI на `/docs`, убедитесь, что одновременно заданы две переменные окружения:

 1. `WEB_API_ENABLED=true` — включает само веб-API.
-2. `WEB_API_DOCS_ENABLED=true` — публикует `/docs`, `/redoc` и `/openapi.json`.
+2. `WEB_API_DOCS_ENABLED=true` — публикует `/docs`, `/scalar` и `/openapi.json`.

 После изменения значений перезапустите бота. Интерфейс будет доступен по адресу `http://<WEB_API_HOST>:<WEB_API_PORT>/docs`.

@@ -128,7 +128,7 @@ curl -X POST "http://127.0.0.1:8080/tokens" \
 | `DELETE` | `/promo-groups/{id}` | Удалить промо-группу.
 | `GET` | `/tokens` | Управление токенами доступа.

-> Все списковые эндпоинты поддерживают пагинацию (`limit`, `offset`) и фильтры, описанные в OpenAPI спецификации. Если `WEB_API_DOCS_ENABLED=true`, документация доступна по `/docs`. В ответах `/settings` поле `choices` всегда массив: пустой список означает отсутствие предопределённых значений.
+> Все списковые эндпоинты поддерживают пагинацию (`limit`, `offset`) и фильтры, описанные в OpenAPI спецификации. Если `WEB_API_DOCS_ENABLED=true`, интерактивные интерфейсы документации доступны по `/docs` (Swagger UI) и `/scalar` (Scalar). В ответах `/settings` поле `choices` всегда массив: пустой список означает отсутствие предопределённых значений.

 ## 7. Сценарий интеграции веб-админки