feat: add scalar configuration (#4162)

Author: skv0zsneg

litestar/openapi/plugins.py

@@ -16,6 +16,7 @@
     from litestar.connection import Request
     from litestar.router import Router
 
+
 __all__ = (
     "OpenAPIRenderPlugin",
     "RapidocRenderPlugin",
@@ -363,6 +364,7 @@ def __init__(
         js_url: str | None = None,
         css_url: str | None = None,
         path: str | Sequence[str] = "/scalar",
+        options: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> None:
         """Initialize the Scalar OpenAPI UI render plugin.
@@ -375,10 +377,13 @@ def __init__(
             css_url: Download url for the Scalar CSS bundle.
                 If not provided, the Litestar-provided CSS will be used.
             path: Path to serve the OpenAPI UI at.
+            options: Scalar configuration options.
+                If not provided the default Scalar configuration will be used.
             **kwargs: Additional arguments to pass to the base class.
         """
         self.js_url = js_url or f"https://cdn.jsdelivr.net/npm/@scalar/api-reference@{version}"
         self.css_url = css_url or self._default_css_url
+        self.options = options
         super().__init__(path=path, **kwargs)
 
     def render(self, request: Request, openapi_schema: dict[str, Any]) -> bytes:
@@ -412,6 +417,7 @@ def render(self, request: Request, openapi_schema: dict[str, Any]) -> bytes:
                   id="api-reference"
                   data-url="{self.get_openapi_json_route(request)}">
                 </script>
+                {self.render_options()}
                 <script src="{self.js_url}" crossorigin></script>
                 """
 
@@ -423,6 +429,16 @@ def render(self, request: Request, openapi_schema: dict[str, Any]) -> bytes:
                     </html>
                 """.encode()
 
+    def render_options(self) -> str:
+        """Render options to Scalar configuration."""
+        if not self.options:
+            return ""
+        return f"""
+                <script>
+                  document.getElementById('api-reference').dataset.configuration = '{msgspec.json.encode(self.options).decode()}'
+                </script>
+                """
+
 
 class StoplightRenderPlugin(OpenAPIRenderPlugin):
     """Render an OpenAPI schema using StopLight Elements."""

tests/unit/test_openapi/test_plugins.py

@@ -1,7 +1,9 @@
+import pytest
+
 from litestar import Litestar
 from litestar.config.csrf import CSRFConfig
 from litestar.openapi.config import OpenAPIConfig
-from litestar.openapi.plugins import RapidocRenderPlugin, SwaggerRenderPlugin
+from litestar.openapi.plugins import RapidocRenderPlugin, ScalarRenderPlugin, SwaggerRenderPlugin
 from litestar.testing import TestClient
 
 rapidoc_fragment = ".addEventListener('before-try',"
@@ -60,3 +62,30 @@ def test_plugins_csrf_httponly() -> None:
         resp = client.get("/schema/swagger")
         assert resp.status_code == 200
         assert swagger_fragment not in resp.text
+
+
+@pytest.mark.parametrize(
+    "scalar_config",
+    [
+        {"showSidebar": False},
+    ],
+)
+@pytest.mark.parametrize(
+    "expected_config_render",
+    [
+        "document.getElementById('api-reference').dataset.configuration = '{\"showSidebar\":false}'",
+    ],
+)
+def test_openapi_scalar_options(scalar_config: dict, expected_config_render: str) -> None:
+    app = Litestar(
+        openapi_config=OpenAPIConfig(
+            title="Litestar Example",
+            version="0.0.1",
+            render_plugins=[ScalarRenderPlugin(options=scalar_config)],
+        )
+    )
+
+    with TestClient(app=app) as client:
+        resp = client.get("/schema/scalar")
+        assert resp.status_code == 200
+        assert expected_config_render in resp.text