Refactor API contracts to Zod, zod-to-openapi, and Scalar.

Replace hand-written OpenAPI and Swagger UI with schema-driven docs at /api-docs and Zod validation on request bodies.

Co-authored-by: Cursor <cursoragent@cursor.com>

src/index.ts

@@ -1,5 +1,5 @@
 import express from "express";
-import swaggerUi from "swagger-ui-express";
+import { apiReference } from "@scalar/express-api-reference";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,7 +8,7 @@ import { bootstrap, config } from "./composition/bootstrap.js";
 import { runtime } from "./infrastructure/config/runtime.js";
 import { SseHub } from "./interfaces/sse/sse.js";
 import { createRouter } from "./interfaces/http/routes.js";
-import { openapiSpec } from "./interfaces/http/openapi.js";
+import { openapiDocument } from "./interfaces/http/openapi.js";
 
 const log = createLogger("server");
 
@@ -26,10 +26,13 @@ function main(): void {
   server.use(express.json());
   server.use("/api", createRouter(ctx.application, sse));
 
-  server.use("/api-docs", swaggerUi.serve, swaggerUi.setup(openapiSpec, {
-    customSiteTitle: "Arb Pulse — API Docs",
-    swaggerOptions: { defaultModelsExpandDepth: 2, defaultModelExpandDepth: 2 },
-  }));
+  server.use(
+    "/api-docs",
+    apiReference({
+      content: openapiDocument,
+      pageTitle: "Arb Pulse — API Docs",
+    }),
+  );
 
   if (existsSync(webDist)) {
     server.use(express.static(webDist));
@@ -40,7 +43,9 @@ function main(): void {
     server.get("/", (_req, res) => {
       res
         .status(200)
-        .send("Backend running. Frontend not built yet — run `npm run build` (or `npm run dev:web`).");
+        .send(
+          "Backend running. Frontend not built yet — run `npm run build` (or `npm run dev:web`).",
+        );
     });
   }