feat: add Scalar API docs alongside Swagger UI

.gitignore

@@ -7,3 +7,11 @@
 __pycache__/
 *.pyc
 *.cover
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "pymysql>=1.1.0",
     "langchain>=0.3.9",
     "mcp>=1.27.1",
+    "scalar-fastapi>=1.0.3",
 ]
 
 [project.optional-dependencies]

scripts/test_cli_dev_studio_smoke.py

@@ -158,7 +158,8 @@ def main() -> int:
         logs = log_path.read_text(encoding="utf-8", errors="replace")
         assert "> Ready!" in logs, logs
         assert f"> - API: http://localhost:{api_port}" in logs, logs
-        assert f"> - Docs: http://localhost:{api_port}/docs" in logs, logs
+        assert f"> - Docs (Swagger): http://localhost:{api_port}/docs" in logs, logs
+        assert f"> - Docs (Scalar): http://localhost:{api_port}/scalar-docs" in logs, logs
         assert (
             "https://smith.langchain.com/studio/?baseUrl="
             f"http://127.0.0.1:{api_port}"

src/agentseek_api/cli.py

@@ -67,6 +67,7 @@ class CliConfig:
 class DevServerUrls:
     api_url: str
     docs_url: str
+    scalar_docs_url: str
     studio_url: str
 
 
@@ -324,6 +325,7 @@ def _resolve_dev_urls(*, host: str, port: int, studio_url: str | None) -> DevSer
     return DevServerUrls(
         api_url=api_url,
         docs_url=f"{api_url}/docs",
+        scalar_docs_url=f"{api_url}/scalar-docs",
         studio_url=f"{studio_origin}/studio/?baseUrl={studio_base_url}",
     )
 
@@ -334,7 +336,9 @@ def _render_dev_ready_banner(urls: DevServerUrls) -> str:
         ">\n"
         f"> - API: {urls.api_url}\n"
         ">\n"
-        f"> - Docs: {urls.docs_url}\n"
+        f"> - Docs (Swagger): {urls.docs_url}\n"
+        ">\n"
+        f"> - Docs (Scalar): {urls.scalar_docs_url}\n"
         ">\n"
         f"> - LangSmith Studio Web UI: {urls.studio_url}\n"
     )

src/agentseek_api/main.py

@@ -5,7 +5,8 @@
 from typing import Any
 
 from fastapi import Depends, FastAPI, HTTPException, Query, Request, Response
-from fastapi.responses import JSONResponse, PlainTextResponse
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
+from scalar_fastapi import get_scalar_api_reference
 from starlette.routing import Route
 
 from agentseek_api import __version__
@@ -156,6 +157,14 @@ async def health() -> dict[str, str]:
     async def ok() -> dict[str, bool]:
         return {"ok": True}
 
+    @app.get("/scalar-docs", include_in_schema=False)
+    async def scalar_docs() -> HTMLResponse:
+        return get_scalar_api_reference(
+            openapi_url=app.openapi_url,
+            title=f"{settings.APP_NAME} - Scalar",
+            persist_auth=True,
+        )
+
     @app.get("/info")
     async def info() -> dict[str, object]:
         return {

tests/unit/test_cli.py

@@ -362,6 +362,7 @@ def test_resolve_dev_urls_use_localhost_display_and_loopback_base_url() -> None:
 
     assert urls.api_url == "http://localhost:2024"
     assert urls.docs_url == "http://localhost:2024/docs"
+    assert urls.scalar_docs_url == "http://localhost:2024/scalar-docs"
     assert urls.studio_url == "https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024"
 
 
@@ -372,6 +373,7 @@ def test_resolve_dev_urls_preserve_explicit_host_and_override_studio_origin() ->
 
     assert urls.api_url == "http://devbox.local:3030"
     assert urls.docs_url == "http://devbox.local:3030/docs"
+    assert urls.scalar_docs_url == "http://devbox.local:3030/scalar-docs"
     assert urls.studio_url == "https://smith.example.com/studio/?baseUrl=http://devbox.local:3030"
 
 
@@ -413,7 +415,8 @@ def terminate(self) -> None:
     assert exit_code == 0
     assert "> Ready!" in stdout.getvalue()
     assert "- API: http://localhost:2024" in stdout.getvalue()
-    assert "- Docs: http://localhost:2024/docs" in stdout.getvalue()
+    assert "- Docs (Swagger): http://localhost:2024/docs" in stdout.getvalue()
+    assert "- Docs (Scalar): http://localhost:2024/scalar-docs" in stdout.getvalue()
     assert "https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024" in stdout.getvalue()
     assert opened == ["https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024"]