macss-modular-api 0.4.3__tar.gz → 0.4.5__tar.gz

{macss_modular_api-0.4.3/src/macss_modular_api.egg-info → macss_modular_api-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.3
+Version: 0.4.5
 Summary: Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically.
 Author: ccisne.dev
 License-Expression: MIT
@@ -114,7 +114,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -122,7 +122,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -130,13 +130,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/README.md

@@ -79,7 +79,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -87,7 +87,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -95,13 +95,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macss-modular-api"
-version = "0.4.3"
+version = "0.4.5"
 description = "Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically."
 readme = "README.md"
 license = "MIT"

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5/src/macss_modular_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.3
+Version: 0.4.5
 Summary: Use-case-centric toolkit for building modular APIs with Starlette. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose OpenAPI documentation automatically.
 Author: ccisne.dev
 License-Expression: MIT
@@ -114,7 +114,7 @@ pip install modular-api[serve]
 ## Error handling
 
 ```python
-async def execute(self) -> None:
+async def execute(self) -> FoundUserOutput:
     user = await repository.find_by_id(self.input.user_id)
     if not user:
         raise UseCaseException(
@@ -122,7 +122,7 @@ async def execute(self) -> None:
             message="User not found",
             error_code="USER_NOT_FOUND",
         )
-    self._output = FoundUserOutput(name=user.name)
+    return FoundUserOutput(name=user.name)
 ```
 
 ---
@@ -130,13 +130,13 @@ async def execute(self) -> None:
 ## Testing
 
 ```python
-def test_hello_world():
+async def test_hello_world():
     usecase = HelloWorld(HelloInput(name="World"))
     error = usecase.validate()
     assert error is None
 
-    await usecase.execute()
-    assert usecase.output.message == "Hello, World!"
+    output = await usecase.execute()
+    assert output.message == "Hello, World!"
 ```
 
 See [doc/testing_guide.md](doc/testing_guide.md) for the full testing guide.

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/src/modular_api/core/modular_api.py

@@ -59,6 +59,7 @@ class ModularApi:
         title: str = "Modular API",
         version: str = "0.0.0",
         release_id: str | None = None,
+        servers: list[dict[str, str]] | None = None,
         metrics_enabled: bool = False,
         metrics_path: str = "/metrics",
         log_level: LogLevel = LogLevel.info,
@@ -67,6 +68,7 @@ class ModularApi:
         self._title = title
         self._version = version
         self._release_id = release_id or f"{version}-debug"
+        self._servers = servers
         self._metrics_enabled = metrics_enabled
         self._metrics_path = metrics_path
         self._log_level = log_level
@@ -188,6 +190,8 @@ class ModularApi:
 
         # OpenAPI endpoints
         spec_kwargs: dict[str, Any] = {"title": self._title, "port": port, "version": self._version}
+        if self._servers is not None:
+            spec_kwargs["servers"] = self._servers
         routes.append(Route("/openapi.json", endpoint=openapi_json_handler(**spec_kwargs)))
         routes.append(Route("/openapi.yaml", endpoint=openapi_yaml_handler(**spec_kwargs)))
 

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/src/modular_api/core/usecase.py

@@ -49,13 +49,15 @@ def _normalize_schema(raw: dict[str, Any]) -> dict[str, object]:
                 # Convert examples → example (nullable fields)
                 if "examples" in prop and prop["examples"]:
                     collapsed["example"] = prop["examples"][0]
+                collapsed.pop("additionalProperties", None)
                 normalized_props[name] = _reorder_type_first(collapsed)
                 if name in required:
                     required.remove(name)
                 continue
 
-        # Strip Pydantic's auto-generated ``title`` and ``default`` from properties
-        cleaned = {k: v for k, v in prop.items() if k not in ("title", "default")}
+        # Strip Pydantic's auto-generated ``title``, ``default``, and
+        # ``additionalProperties`` (emitted for dict[str, Any] fields) from properties.
+        cleaned = {k: v for k, v in prop.items() if k not in ("title", "default", "additionalProperties")}
 
         # Convert Pydantic ``examples`` (list, Draft 2020-12) → OpenAPI ``example`` (singular)
         if "examples" in cleaned and cleaned["examples"]:

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/src/modular_api/core/usecase_handler.py

@@ -8,7 +8,6 @@ the full use-case lifecycle: parse → validate → execute → respond.
 from __future__ import annotations
 
 import json
-import sys
 from typing import Any, Callable
 
 from pydantic import ValidationError
@@ -114,7 +113,9 @@ def usecase_handler(factory: UseCaseFactory) -> Any:
             )
 
         except UseCaseException as exc:
-            print(f"UseCaseException: {exc}", file=sys.stderr)
+            logger = getattr(request.state, LOGGER_STATE_KEY, None)
+            if logger is not None:
+                logger.error("UseCaseException", fields={"error": str(exc), "status": exc.status_code})
             return Response(
                 content=json.dumps(exc.to_json()),
                 status_code=exc.status_code,
@@ -131,7 +132,9 @@ def usecase_handler(factory: UseCaseFactory) -> Any:
                 media_type=_JSON_CONTENT_TYPE,
             )
         except Exception as exc:
-            print(f"usecase_handler unexpected error: {exc}", file=sys.stderr)
+            logger = getattr(request.state, LOGGER_STATE_KEY, None)
+            if logger is not None:
+                logger.error("Unexpected error in use case handler", fields={"error": str(exc)})
             return Response(
                 content=json.dumps({"error": "Internal server error"}),
                 status_code=500,

macss_modular_api-0.4.5/src/modular_api/openapi/swagger_docs.py

@@ -0,0 +1,48 @@
+"""Docs UI handler — serves the ``@macss/docs-ui`` widget from CDN.
+
+Loads ``@macss/docs-ui`` from jsdelivr CDN, which wraps Swagger UI with
+system-aware dark mode.  The local ``/openapi.json`` endpoint provides
+the spec.  Styling, dark mode, and Swagger UI loading are handled
+entirely by docs-ui — no inline CSS or JS in this template.
+
+See: https://github.com/macss-dev/modular_api/tree/main/docs-ui
+"""
+
+from __future__ import annotations
+
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+
+_DOCS_UI_CDN = "https://cdn.jsdelivr.net/npm/@macss/docs-ui@0.1/dist"
+
+# {title} is the only placeholder — str.replace() is a literal match,
+# so JavaScript braces pass through unaffected.
+_DOCS_UI_HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>{title} — API Reference</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="swagger-ui"></div>
+    <script src=""" + f'"{_DOCS_UI_CDN}/docs-ui.js"' + """></script>
+    <script>DocsUI.init({ specUrl: "/openapi.json" })</script>
+  </body>
+</html>"""
+
+
+def swagger_docs_handler(*, title: str) -> object:
+    """Return a Starlette endpoint that serves a docs-ui HTML page.
+
+    Usage::
+
+        Route("/docs", endpoint=swagger_docs_handler(title="My API"))
+    """
+    html = _DOCS_UI_HTML_TEMPLATE.replace("{title}", title)
+
+    async def _endpoint(request: Request) -> HTMLResponse:
+        return HTMLResponse(html)
+
+    return _endpoint

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/tests/test_fromjson_validation.py

@@ -9,6 +9,7 @@ Error message contract (identical across all 3 SDKs for parity):
 """
 
 import json
+from typing import Any
 
 import pytest
 from pydantic import Field, ValidationError
@@ -120,3 +121,28 @@ class TestFromJsonHandlerErrors:
         assert resp.status_code == 200
         body = resp.json()
         assert body["greeting"] == "Hi Alice, age 25"
+
+
+# ── Unit: dict[str, Any] object type validation ──────────────────────────
+
+
+class ObjectInput(Input):
+    id: str = Field(description="ID")
+    details: dict[str, Any] = Field(description="Nested object")
+
+
+class TestFromJsonObjectType:
+    """Pydantic strict mode validates dict[str, Any] as object type."""
+
+    def test_accepts_dict_for_object_field(self) -> None:
+        result = ObjectInput.from_json({"id": "abc", "details": {"amount": 100}})
+        assert result.id == "abc"
+        assert result.details == {"amount": 100}
+
+    def test_rejects_string_for_object_field(self) -> None:
+        with pytest.raises(ValidationError):
+            ObjectInput.from_json({"id": "abc", "details": "not-a-dict"})
+
+    def test_rejects_list_for_object_field(self) -> None:
+        with pytest.raises(ValidationError):
+            ObjectInput.from_json({"id": "abc", "details": [1, 2]})

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/tests/test_modular_api.py

@@ -205,10 +205,57 @@ class TestAutoMountedEndpoints:
         response = client.get("/docs")
         assert response.status_code == 200
         assert "text/html" in response.headers["content-type"]
-        assert "swagger-ui-dist@5" in response.text
+        assert "@macss/docs-ui" in response.text
         assert "Test API" in response.text
 
 
+# ── Custom servers in OpenAPI spec ────────────────────────────
+
+
+class TestCustomServers:
+    """ModularApi propagates servers to the OpenAPI spec."""
+
+    def _build_client(self, **api_options: object) -> TestClient:
+        api = _make_api(**api_options)
+        api.module("test", lambda m: m.usecase("ping", _PingUseCase.from_json))
+        app = api.build()
+        return TestClient(app)
+
+    def test_uses_localhost_default_when_servers_not_provided(self) -> None:
+        client = self._build_client()
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 1
+        assert "localhost" in spec["servers"][0]["url"]
+
+    def test_propagates_custom_servers_to_openapi_spec(self) -> None:
+        client = self._build_client(
+            servers=[{"url": "https://miapi.example.com", "description": "Production"}],
+        )
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 1
+        assert spec["servers"][0]["url"] == "https://miapi.example.com"
+        assert spec["servers"][0]["description"] == "Production"
+
+    def test_supports_multiple_servers(self) -> None:
+        client = self._build_client(
+            servers=[
+                {"url": "https://prod.example.com", "description": "Production"},
+                {"url": "http://192.168.5.82:8080", "description": "LAN"},
+            ],
+        )
+        spec = client.get("/openapi.json").json()
+        assert len(spec["servers"]) == 2
+        assert spec["servers"][0]["url"] == "https://prod.example.com"
+        assert spec["servers"][1]["url"] == "http://192.168.5.82:8080"
+
+    def test_preserves_server_descriptions(self) -> None:
+        client = self._build_client(
+            servers=[{"url": "https://api.example.com", "description": "Main API"}],
+        )
+        spec = client.get("/openapi.json").json()
+        assert spec["servers"][0]["description"] == "Main API"
+
+
 # ── Step 2.9.3: Middleware pipeline order ─────────────────────
 
 

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/tests/test_schema_conformance.py

@@ -4,14 +4,19 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any
 
 import sys
 
+from pydantic import Field
+
 _EXAMPLE_DIR = Path(__file__).resolve().parent.parent / "example"
 sys.path.insert(0, str(_EXAMPLE_DIR))
 
 from modules.greetings.usecases.hello_world import HelloWorldInput, HelloWorldOutput  # type: ignore[import-untyped]
 
+from modular_api.core.usecase import Input
+
 _FIXTURES = Path(__file__).resolve().parent.parent.parent / "tests" / "fixtures"
 
 
@@ -48,3 +53,16 @@ class TestSchemaConformance:
     def test_hello_output_to_json(self) -> None:
         instance = HelloWorldOutput(message="Hello!")
         assert instance.to_json() == {"message": "Hello!"}
+
+
+class WebhookInput(Input):
+    instruction_id: str = Field(description="Payment instruction ID", examples=["20260323ABC"])
+    transfer_details: dict[str, Any] = Field(description="Nested transfer info", examples=[{"amount": 2300, "currency": "PEN"}])
+
+
+class TestSchemaConformanceObjectType:
+    """Verify dict[str, Any] produces a schema identical to the shared fixture."""
+
+    def test_webhook_input_schema_matches_fixture(self) -> None:
+        fixture = _load_fixture("webhook_input_schema.json")
+        assert WebhookInput.to_schema() == fixture

{macss_modular_api-0.4.3 → macss_modular_api-0.4.5}/tests/test_usecase_handler.py

@@ -205,3 +205,80 @@ class TestUseCaseLifecycle:
         client = TestClient(app)
         client.post("/spy", json={})
         assert captured_loggers == ["fake-logger"]
+
+
+# ── Scoped-logger error integration (issue #7) ───────────────────────────
+
+
+class TestScopedLoggerInErrorPaths:
+    """Catch blocks must log through the request-scoped logger (with trace_id)
+    instead of printing to stderr."""
+
+    @staticmethod
+    def _build_app_with_logger(
+        factory,
+        log_lines: list[str],
+    ) -> Starlette:
+        """App with logging middleware capturing output into log_lines."""
+        from starlette.middleware import Middleware
+
+        from modular_api.core.logger.logging_middleware import logging_middleware
+        from modular_api.core.logger.logger import LogLevel
+
+        mw_cls = logging_middleware(
+            log_level=LogLevel.debug,
+            service_name="test-svc",
+            write_fn=lambda line: log_lines.append(line),
+        )
+        return Starlette(
+            routes=[Route("/test", usecase_handler(factory), methods=["POST"])],
+            middleware=[Middleware(mw_cls)],
+        )
+
+    def test_logs_use_case_exception_through_scoped_logger(self) -> None:
+        log_lines: list[str] = []
+        app = self._build_app_with_logger(FailingUseCase, log_lines)
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post(
+            "/test",
+            json={"name": "x"},
+            headers={"X-Request-ID": "trace-py-uce-001"},
+        )
+        assert resp.status_code == 409
+
+        error_logs = [
+            json.loads(l)
+            for l in log_lines
+            if '"level": "error"' in l and "UseCaseException" in l
+        ]
+        assert len(error_logs) > 0, "expected error log from scoped logger"
+        assert error_logs[0]["trace_id"] == "trace-py-uce-001"
+
+    def test_logs_unexpected_error_through_scoped_logger(self) -> None:
+        log_lines: list[str] = []
+        app = self._build_app_with_logger(CrashingUseCase, log_lines)
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post(
+            "/test",
+            json={"name": "x"},
+            headers={"X-Request-ID": "trace-py-crash-002"},
+        )
+        assert resp.status_code == 500
+
+        error_logs = [
+            json.loads(l)
+            for l in log_lines
+            if '"level": "error"' in l and "Unexpected error" in l
+        ]
+        assert len(error_logs) > 0, "expected error log from scoped logger"
+        assert error_logs[0]["trace_id"] == "trace-py-crash-002"
+
+    def test_does_not_throw_when_logger_unavailable(self) -> None:
+        """When no logging middleware is present, catch blocks must not crash."""
+        app = Starlette(
+            routes=[Route("/test", usecase_handler(FailingUseCase), methods=["POST"])],
+        )
+        client = TestClient(app, raise_server_exceptions=False)
+        resp = client.post("/test", json={"name": "x"})
+        assert resp.status_code == 409
+        assert resp.json()["message"] == "Already exists"

macss_modular_api-0.4.3/src/modular_api/openapi/swagger_docs.py

@@ -1,228 +0,0 @@
-"""Swagger UI docs handler — serves a self-contained interactive API explorer.
-
-Loads swagger-ui-dist@5 (CSS + JS bundle) from the jsdelivr CDN and
-points the UI at the local ``/openapi.json`` endpoint.  No server-side
-dependencies; no npm packages required.  Replaces the previous Scalar
-widget as specified by PRD-003.
-"""
-
-from __future__ import annotations
-
-from starlette.requests import Request
-from starlette.responses import HTMLResponse
-
-# Canonical Swagger UI HTML per PRD-003.
-# Uses {title} as a plain str.replace() placeholder — Python's replace()
-# is a literal match, so JavaScript braces pass through unaffected.
-_SWAGGER_UI_HTML_TEMPLATE = """\
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>{title} — API Reference</title>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <link
-      rel="stylesheet"
-      href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"
-    />
-    <style>
-      /* ── Light mode baseline (Swagger UI default) ───────────── */
-      :root {
-        --bg-primary:   #ffffff;
-        --bg-secondary: #f7f7f7;
-        --bg-block:     #ffffff;
-        --border-color: #e8e8e8;
-        --text-primary: #3b4151;
-        --text-muted:   #6b7280;
-        --input-bg:     #ffffff;
-        --input-text:   #3b4151;
-        --input-border: #d9d9d9;
-      }
-
-      /* ── Dark mode overrides ───────────────────────────── */
-      @media (prefers-color-scheme: dark) {
-        :root {
-          --bg-primary:   #1a1a1a;
-          --bg-secondary: #222222;
-          --bg-block:     #2a2a2a;
-          --border-color: #3a3a3a;
-          --text-primary: #e0e0e0;
-          --text-muted:   #a0a0a0;
-          --input-bg:     #2a2a2a;
-          --input-text:   #e0e0e0;
-          --input-border: #444444;
-        }
-
-        body {
-          background-color: var(--bg-primary);
-        }
-
-        /* ── General text ──────────────────────────────── */
-        .swagger-ui,
-        .swagger-ui .info .title,
-        .swagger-ui .info p,
-        .swagger-ui .info li,
-        .swagger-ui .info a,
-        .swagger-ui .opblock-tag,
-        .swagger-ui .opblock-tag small,
-        .swagger-ui table thead tr td,
-        .swagger-ui table thead tr th,
-        .swagger-ui .response-col_status,
-        .swagger-ui .response-col_description,
-        .swagger-ui .parameter__name,
-        .swagger-ui .parameter__type,
-        .swagger-ui .parameter__in,
-        .swagger-ui .tab li,
-        .swagger-ui .model-title,
-        .swagger-ui .model,
-        .swagger-ui .prop-type,
-        .swagger-ui .prop-format {
-          color: var(--text-primary);
-        }
-
-        /* ── Backgrounds ───────────────────────────────── */
-        .swagger-ui .wrapper,
-        .swagger-ui .scheme-container,
-        .swagger-ui section.models,
-        .swagger-ui section.models .model-container,
-        .swagger-ui .model-box {
-          background: var(--bg-secondary);
-          border-color: var(--border-color);
-        }
-
-        /* ── Operation blocks ────────────────────────────── */
-        .swagger-ui .opblock {
-          background: var(--bg-block);
-          border-color: var(--border-color);
-          box-shadow: none;
-        }
-
-        .swagger-ui .opblock .opblock-summary {
-          background: var(--bg-block);
-          border-color: var(--border-color);
-        }
-
-        .swagger-ui .opblock .opblock-section-header {
-          background: var(--bg-secondary);
-          border-color: var(--border-color);
-        }
-
-        .swagger-ui .opblock .opblock-section-header h4 {
-          color: var(--text-primary);
-        }
-
-        /* HTTP method accent colors preserved in dark mode */
-        .swagger-ui .opblock.opblock-post   { border-color: #49cc90; }
-        .swagger-ui .opblock.opblock-get    { border-color: #61affe; }
-        .swagger-ui .opblock.opblock-put    { border-color: #fca130; }
-        .swagger-ui .opblock.opblock-delete { border-color: #f93e3e; }
-        .swagger-ui .opblock.opblock-patch  { border-color: #50e3c2; }
-
-        .swagger-ui .opblock.opblock-post   .opblock-summary-method { background: #49cc90; }
-        .swagger-ui .opblock.opblock-get    .opblock-summary-method { background: #61affe; }
-        .swagger-ui .opblock.opblock-put    .opblock-summary-method { background: #fca130; }
-        .swagger-ui .opblock.opblock-delete .opblock-summary-method { background: #f93e3e; }
-        .swagger-ui .opblock.opblock-patch  .opblock-summary-method { background: #50e3c2; }
-
-        /* ── Inputs and controls ─────────────────────────── */
-        .swagger-ui input[type=text],
-        .swagger-ui input[type=password],
-        .swagger-ui input[type=search],
-        .swagger-ui input[type=email],
-        .swagger-ui textarea,
-        .swagger-ui select {
-          background: var(--input-bg);
-          color: var(--input-text);
-          border-color: var(--input-border);
-        }
-
-        /* ── Buttons ───────────────────────────────────── */
-        .swagger-ui .btn {
-          background: var(--bg-block);
-          color: var(--text-primary);
-          border-color: var(--border-color);
-        }
-
-        .swagger-ui .btn.execute {
-          background: #4a90e2;
-          color: #ffffff;
-          border-color: #4a90e2;
-        }
-
-        .swagger-ui .btn.authorize {
-          color: #49cc90;
-          border-color: #49cc90;
-        }
-
-        /* ── Response area ─────────────────────────────── */
-        .swagger-ui .responses-inner,
-        .swagger-ui .response-col_description__inner {
-          background: var(--bg-secondary);
-          color: var(--text-primary);
-        }
-
-        .swagger-ui .highlight-code,
-        .swagger-ui .microlight {
-          background: #111111 !important;
-          color: #e0e0e0 !important;
-        }
-
-        /* ── Topbar ────────────────────────────────────── */
-        .swagger-ui .topbar {
-          background-color: #111111;
-        }
-
-        /* ── Expand/collapse arrows ──────────────────────── */
-        .swagger-ui .expand-methods svg,
-        .swagger-ui .expand-operation svg {
-          fill: var(--text-muted);
-        }
-
-        /* ── Filter input ──────────────────────────────── */
-        .swagger-ui .filter .operation-filter-input {
-          background: var(--input-bg);
-          color: var(--input-text);
-          border-color: var(--input-border);
-        }
-
-        /* ── Scrollbar (webkit) ──────────────────────────── */
-        ::-webkit-scrollbar { width: 8px; height: 8px; }
-        ::-webkit-scrollbar-track { background: var(--bg-primary); }
-        ::-webkit-scrollbar-thumb { background: #444444; border-radius: 4px; }
-        ::-webkit-scrollbar-thumb:hover { background: #555555; }
-      }
-    </style>
-  </head>
-  <body>
-    <div id="swagger-ui"></div>
-    <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js">
-    </script>
-    <script>
-      SwaggerUIBundle({
-        url: "/openapi.json",
-        dom_id: "#swagger-ui",
-        presets: [
-          SwaggerUIBundle.presets.apis,
-          SwaggerUIBundle.SwaggerUIStandalonePreset
-        ],
-        layout: "BaseLayout",
-        deepLinking: true
-      })
-    </script>
-  </body>
-</html>"""
-
-
-def swagger_docs_handler(*, title: str) -> object:
-    """Return a Starlette endpoint that serves a Swagger UI HTML page.
-
-    Usage::
-
-        Route("/docs", endpoint=swagger_docs_handler(title="My API"))
-    """
-    html = _SWAGGER_UI_HTML_TEMPLATE.replace("{title}", title)
-
-    async def _endpoint(request: Request) -> HTMLResponse:
-        return HTMLResponse(html)
-
-    return _endpoint