macss-modular-api 0.4.2__tar.gz → 0.4.4__tar.gz

{macss_modular_api-0.4.2/src/macss_modular_api.egg-info → macss_modular_api-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.2
+Version: 0.4.4
 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

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macss-modular-api"
-version = "0.4.2"
+version = "0.4.4"
 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.2 → macss_modular_api-0.4.4/src/macss_modular_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macss-modular-api
-Version: 0.4.2
+Version: 0.4.4
 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

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/src/modular_api/core/module_builder.py

@@ -91,7 +91,7 @@ class ModuleBuilder:
 
     def usecase(
         self,
-        name: str,
+        command: str,
         factory: UseCaseFactory,
         *,
         method: str = "POST",
@@ -100,15 +100,19 @@ class ModuleBuilder:
     ) -> ModuleBuilder:
         """Register a use case as an HTTP endpoint on this module.
 
+        ``command`` becomes the route segment and the OpenAPI operationId root.
+        Convention: command, class name, and file name share the same root.
+        Example: command ``'hello-world'`` → class ``HelloWorld`` → file ``hello_world.py``.
+
         Returns ``self`` for fluent chaining.
         """
-        clean_name = name.strip().lstrip("/")
+        clean_command = command.strip().lstrip("/")
         method_upper = method.upper()
-        full_path = f"{self._normalize_base(self._base_path)}/{self._module_name}/{clean_name}"
+        full_path = f"{self._normalize_base(self._base_path)}/{self._module_name}/{clean_command}"
 
         # Mount endpoint on internal route list
         self._routes.append(
-            Route(f"/{clean_name}", endpoint=usecase_handler(factory), methods=[method_upper]),
+            Route(f"/{clean_command}", endpoint=usecase_handler(factory), methods=[method_upper]),
         )
 
         # Capture schemas via a dummy factory call (fail-safe)
@@ -116,15 +120,15 @@ class ModuleBuilder:
 
         # Register metadata for OpenAPI generation
         doc = UseCaseDocMeta(
-            summary=summary or f"Use case {clean_name} in module {self._module_name}",
-            description=description or f"Auto-generated documentation for {clean_name}",
+            summary=summary or f"Use case {clean_command} in module {self._module_name}",
+            description=description or f"Auto-generated documentation for {clean_command}",
             tags=[self._module_name],
         )
 
         api_registry.routes.append(
             UseCaseRegistration(
                 module=self._module_name,
-                name=clean_name,
+                command=clean_command,
                 method=method_upper,
                 path=full_path,
                 factory=factory,
@@ -145,16 +149,12 @@ class ModuleBuilder:
     def _extract_schemas(factory: UseCaseFactory) -> dict[str, dict[str, Any]]:
         """Capture Input and Output schemas from a UseCase factory.
 
-        Strategy (in order of preference):
-        1. Class-level extraction via ``to_schema()`` classmethod on BaseModel DTOs.
-           Inspects the factory's type hints to find the Input/Output classes.
-        2. Fallback: instantiate via ``factory({})`` and call ``to_schema()``
-           on the resulting UseCase's input/output (legacy pattern).
+        Uses class-level extraction via ``to_schema()`` classmethod on BaseModel DTOs.
+        Inspects the factory's type hints to find the Input/Output classes.
         """
         input_schema: dict[str, Any] = {}
         output_schema: dict[str, Any] = {}
 
-        # --- Strategy 1: class-level extraction from type hints ---
         return_hint = _get_return_type_hint(factory)
 
         if return_hint is not None:
@@ -172,25 +172,6 @@ class ModuleBuilder:
                 except Exception:
                     pass
 
-            if input_schema or output_schema:
-                return {"input": input_schema, "output": output_schema}
-
-        # --- Strategy 2: legacy factory({}) fallback ---
-        try:
-            instance = factory({})
-        except Exception:
-            return {"input": input_schema, "output": output_schema}
-
-        try:
-            input_schema = instance.input.to_schema()
-        except Exception:
-            pass
-
-        try:
-            output_schema = instance.output.to_schema()
-        except Exception:
-            pass
-
         return {"input": input_schema, "output": output_schema}
 
     @staticmethod

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/src/modular_api/core/registry.py

@@ -38,9 +38,9 @@ class UseCaseRegistration:
     """
 
     module: str
-    name: str
+    command: str  # route segment and operationId root, e.g. 'hello-world'
     method: str  # uppercase: "POST" | "GET" | "PUT" | "PATCH" | "DELETE"
-    path: str  # e.g. "/api/users/create"
+    path: str  # e.g. "/api/v1/greetings/hello-world"
     factory: UseCaseFactory
     schemas: dict[str, dict[str, Any]] = field(default_factory=dict)
     doc: UseCaseDocMeta | None = None

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/src/modular_api/core/usecase.py

@@ -172,8 +172,11 @@ O = TypeVar("O", bound=Output)
 class UseCase(ABC, Generic[I, O]):
     """Contract for business logic units.
 
-    Pure interface: all members must be provided by the implementor.
-    No default behavior is inherited — every UseCase is self-contained.
+    Lifecycle (handled by the framework):
+      1. ``from_json(json)``    — static factory, builds the use case
+      2. ``validate()``         — return error string or ``None``
+      3. ``execute()``          — run business logic, return Output
+      4. handler serializes     — ``output.to_json()`` → HTTP response
     """
 
     # Request-scoped logger injected by the framework before execute().
@@ -186,23 +189,12 @@ class UseCase(ABC, Generic[I, O]):
         """Input DTO — set in constructor."""
         ...
 
-    @property
-    @abstractmethod
-    def output(self) -> O:
-        """Output DTO — set in ``execute()``."""
-        ...
-
     @abstractmethod
     def validate(self) -> str | None:
         """Validate the input. Return an error message or ``None``."""
         ...
 
     @abstractmethod
-    async def execute(self) -> None:
-        """Run the business logic and set ``self.output``."""
-        ...
-
-    @abstractmethod
-    def to_json(self) -> dict[str, object]:
-        """Serialize the output for the HTTP response body."""
+    async def execute(self) -> O:
+        """Run the business logic and return the Output."""
         ...

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/src/modular_api/core/usecase_handler.py

@@ -104,12 +104,12 @@ def usecase_handler(factory: UseCaseFactory) -> Any:
                 )
 
             # 4. Execute
-            await use_case.execute()
+            output = await use_case.execute()
 
             # 5. Respond
             return Response(
-                content=json.dumps(use_case.to_json()),
-                status_code=use_case.output.status_code,
+                content=json.dumps(output.to_json()),
+                status_code=output.status_code,
                 media_type=_JSON_CONTENT_TYPE,
             )
 

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/src/modular_api/openapi/openapi.py

@@ -89,8 +89,9 @@ def _add_route_to_spec(
     component_schemas: dict[str, Any],
 ) -> None:
     """Append a single route's path entry, schemas, and operation to the spec."""
-    input_ref_name = f"{route.module}_{route.name}_Input"
-    output_ref_name = f"{route.module}_{route.name}_Output"
+    safe_command = route.command.replace("-", "_")
+    input_ref_name = f"{route.module}_{safe_command}_Input"
+    output_ref_name = f"{route.module}_{safe_command}_Output"
 
     # Store schemas in components
     component_schemas[input_ref_name] = route.schemas.get("input", {"type": "object"})
@@ -102,7 +103,7 @@ def _add_route_to_spec(
     description = route.doc.description if route.doc else None
 
     operation: dict[str, Any] = {
-        "operationId": f"{route.module}_{route.name}_{method_lower}",
+        "operationId": f"{route.module}_{safe_command}_{method_lower}",
         "tags": tags,
         "responses": {
             "200": {

macss_modular_api-0.4.4/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.2 → macss_modular_api-0.4.4}/tests/test_fromjson_validation.py

@@ -41,26 +41,18 @@ class StrictUseCase(UseCase[StrictInput, StrictOutput]):
 
     def __init__(self, data: dict) -> None:
         self._input = StrictInput.from_json(data)
-        self._output = StrictOutput()
 
     @property
     def input(self) -> StrictInput:
         return self._input
 
-    @property
-    def output(self) -> StrictOutput:
-        return self._output
-
     def validate(self) -> str | None:
         if not self.input.name:
             return "name is required"
         return None
 
-    async def execute(self) -> None:
-        self._output = StrictOutput(greeting=f"Hi {self.input.name}, age {self.input.age}")
-
-    def to_json(self) -> dict:
-        return self._output.to_json()
+    async def execute(self) -> StrictOutput:
+        return StrictOutput(greeting=f"Hi {self.input.name}, age {self.input.age}")
 
 
 def _app():

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/tests/test_modular_api.py

@@ -32,24 +32,16 @@ class _PingOutput(Output):
 class _PingUseCase(UseCase[_PingInput, _PingOutput]):
     def __init__(self, inp: _PingInput) -> None:
         self._input = inp
-        self._output = _PingOutput()
 
     @property
     def input(self) -> _PingInput:
         return self._input
 
-    @property
-    def output(self) -> _PingOutput:
-        return self._output
-
     def validate(self) -> str | None:
         return None
 
-    async def execute(self) -> None:
-        self._output = _PingOutput()
-
-    def to_json(self) -> dict:
-        return self.output.to_json()
+    async def execute(self) -> _PingOutput:
+        return _PingOutput()
 
     @staticmethod
     def from_json(json: dict) -> _PingUseCase:
@@ -213,7 +205,7 @@ 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
 
 

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/tests/test_module_builder.py

@@ -34,20 +34,11 @@ class StubUseCase(UseCase[StubInput, StubOutput]):
 
     def __init__(self, input_dto: StubInput) -> None:
         self._input = input_dto
-        self._output = StubOutput(message="")
 
     @property
     def input(self) -> StubInput:
         return self._input
 
-    @property
-    def output(self) -> StubOutput:
-        return self._output
-
-    @output.setter
-    def output(self, value: StubOutput) -> None:
-        self._output = value
-
     @classmethod
     def from_json(cls, json: dict) -> StubUseCase:
         return cls(StubInput.from_json(json))
@@ -57,11 +48,8 @@ class StubUseCase(UseCase[StubInput, StubOutput]):
             return "name is required"
         return None
 
-    async def execute(self) -> None:
-        self.output = StubOutput(message=f"Hello, {self.input.name}!")
-
-    def to_json(self) -> dict:
-        return self.output.to_json()
+    async def execute(self) -> StubOutput:
+        return StubOutput(message=f"Hello, {self.input.name}!")
 
 
 # ── Tests ─────────────────────────────────────────────────────────────────

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/tests/test_schema_conformance.py

@@ -1,4 +1,4 @@
-"""Conformance tests: HelloInput/HelloOutput schemas match shared fixtures."""
+"""Conformance tests: HelloWorldInput/HelloWorldOutput schemas match shared fixtures."""
 
 from __future__ import annotations
 
@@ -10,7 +10,7 @@ import sys
 _EXAMPLE_DIR = Path(__file__).resolve().parent.parent / "example"
 sys.path.insert(0, str(_EXAMPLE_DIR))
 
-from example import HelloInput, HelloOutput  # type: ignore[import-untyped]
+from modules.greetings.usecases.hello_world import HelloWorldInput, HelloWorldOutput  # type: ignore[import-untyped]
 
 _FIXTURES = Path(__file__).resolve().parent.parent.parent / "tests" / "fixtures"
 
@@ -25,26 +25,26 @@ class TestSchemaConformance:
     def test_hello_input_schema_matches_fixture(self) -> None:
         fixture = _load_fixture("hello_input_schema.json")
         # to_schema() is now a classmethod — call on class, not instance
-        assert HelloInput.to_schema() == fixture
+        assert HelloWorldInput.to_schema() == fixture
 
     def test_hello_output_schema_matches_fixture(self) -> None:
         fixture = _load_fixture("hello_output_schema.json")
-        assert HelloOutput.to_schema() == fixture
+        assert HelloWorldOutput.to_schema() == fixture
 
     def test_hello_input_from_json(self) -> None:
         """from_json populates fields correctly."""
-        instance = HelloInput.from_json({"name": "Carlos"})
+        instance = HelloWorldInput.from_json({"name": "Carlos"})
         assert instance.name == "Carlos"
 
     def test_hello_input_to_json(self) -> None:
         """to_json serializes correctly."""
-        instance = HelloInput(name="Carlos")
+        instance = HelloWorldInput(name="Carlos")
         assert instance.to_json() == {"name": "Carlos"}
 
     def test_hello_output_from_json(self) -> None:
-        instance = HelloOutput.from_json({"message": "Hello!"})
+        instance = HelloWorldOutput.from_json({"message": "Hello!"})
         assert instance.message == "Hello!"
 
     def test_hello_output_to_json(self) -> None:
-        instance = HelloOutput(message="Hello!")
+        instance = HelloWorldOutput(message="Hello!")
         assert instance.to_json() == {"message": "Hello!"}

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/tests/test_usecase.py

@@ -32,16 +32,11 @@ class SumUseCase(UseCase[SumInput, SumOutput]):
 
     def __init__(self, input_dto: SumInput) -> None:
         self._input = input_dto
-        self._output = SumOutput(resultado=0)
 
     @property
     def input(self) -> SumInput:
         return self._input
 
-    @property
-    def output(self) -> SumOutput:
-        return self._output
-
     def validate(self) -> str | None:
         if self._input.a is None:
             return "a is required"
@@ -49,13 +44,10 @@ class SumUseCase(UseCase[SumInput, SumOutput]):
             return "b is required"
         return None
 
-    async def execute(self) -> None:
+    async def execute(self) -> SumOutput:
         a = self._input.a or 0
         b = self._input.b or 0
-        self._output = SumOutput(resultado=a + b)
-
-    def to_json(self) -> dict[str, object]:
-        return self._output.to_json()
+        return SumOutput(resultado=a + b)
 
 
 # ── Input tests ─────────────────────────────────────────────────────
@@ -116,16 +108,16 @@ class TestUseCase:
         uc = SumUseCase(SumInput(a=5, b=None))
         assert uc.validate() is not None
 
-    async def test_execute_sets_output(self) -> None:
+    async def test_execute_returns_output(self) -> None:
         uc = SumUseCase(SumInput(a=3, b=4))
         assert uc.validate() is None
-        await uc.execute()
-        assert uc.output.resultado == 7
+        output = await uc.execute()
+        assert output.resultado == 7
 
-    async def test_to_json_returns_output_json(self) -> None:
+    async def test_execute_output_serializes(self) -> None:
         uc = SumUseCase(SumInput(a=10, b=20))
-        await uc.execute()
-        assert uc.to_json() == {"resultado": 30}
+        output = await uc.execute()
+        assert output.to_json() == {"resultado": 30}
 
     def test_logger_defaults_to_none(self) -> None:
         uc = SumUseCase(SumInput(a=1, b=2))

{macss_modular_api-0.4.2 → macss_modular_api-0.4.4}/tests/test_usecase_handler.py

@@ -32,26 +32,18 @@ class GreetUseCase(UseCase[GreetInput, GreetOutput]):
 
     def __init__(self, data: dict) -> None:
         self._input = GreetInput.from_json(data)
-        self._output = GreetOutput()
 
     @property
     def input(self) -> GreetInput:
         return self._input
 
-    @property
-    def output(self) -> GreetOutput:
-        return self._output
-
     def validate(self) -> str | None:
         if not self._input.name:
             return "name is required"
         return None
 
-    async def execute(self) -> None:
-        self._output = GreetOutput(greeting=f"Hello, {self._input.name}!")
-
-    def to_json(self) -> dict:
-        return self._output.to_json()
+    async def execute(self) -> GreetOutput:
+        return GreetOutput(greeting=f"Hello, {self._input.name}!")
 
 
 class FailingUseCase(UseCase[GreetInput, GreetOutput]):
@@ -59,54 +51,38 @@ class FailingUseCase(UseCase[GreetInput, GreetOutput]):
 
     def __init__(self, data: dict) -> None:
         self._input = GreetInput.from_json(data)
-        self._output = GreetOutput()
 
     @property
     def input(self) -> GreetInput:
         return self._input
 
-    @property
-    def output(self) -> GreetOutput:
-        return self._output
-
     def validate(self) -> str | None:
         return None
 
-    async def execute(self) -> None:
+    async def execute(self) -> GreetOutput:
         raise UseCaseException(
             status_code=409,
             message="Already exists",
             error_code="CONFLICT",
         )
 
-    def to_json(self) -> dict:
-        return self._output.to_json()
-
 
 class CrashingUseCase(UseCase[GreetInput, GreetOutput]):
     """Raises an unexpected error during execute."""
 
     def __init__(self, data: dict) -> None:
         self._input = GreetInput(name="x")
-        self._output = GreetOutput()
 
     @property
     def input(self) -> GreetInput:
         return self._input
 
-    @property
-    def output(self) -> GreetOutput:
-        return self._output
-
     def validate(self) -> str | None:
         return None
 
-    async def execute(self) -> None:
+    async def execute(self) -> GreetOutput:
         raise RuntimeError("disk on fire")
 
-    def to_json(self) -> dict:
-        return self._output.to_json()
-
 
 # ── Helpers ───────────────────────────────────────────────────────────────
 
@@ -201,25 +177,17 @@ class TestUseCaseLifecycle:
         class SpyUseCase(UseCase[GreetInput, GreetOutput]):
             def __init__(self, data: dict) -> None:
                 self._input = GreetInput(name="x")
-                self._output = GreetOutput()
 
             @property
             def input(self) -> GreetInput:
                 return self._input
 
-            @property
-            def output(self) -> GreetOutput:
-                return self._output
-
             def validate(self) -> str | None:
                 return None
 
-            async def execute(self) -> None:
+            async def execute(self) -> GreetOutput:
                 captured_loggers.append(self.logger)
-                self._output = GreetOutput(greeting="ok")
-
-            def to_json(self) -> dict:
-                return self._output.to_json()
+                return GreetOutput(greeting="ok")
 
         # Middleware that fakes a logger in request.state
         from starlette.middleware import Middleware

macss_modular_api-0.4.2/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