docs: add OpenAPI descriptions and response schemas for all routes

lib/api/dashboard-public.ts

@@ -55,6 +55,7 @@ export const dashboardPublicRoutes = new Elysia({ prefix: "/dashboard", detail:
 
       return trending.rows
     },
+    { detail: { description: "Trending games based on 7-day benchmark and comment activity." } },
   )
 
   // ── Best Performing New Releases ─────────────────────────────────
@@ -86,6 +87,7 @@ export const dashboardPublicRoutes = new Elysia({ prefix: "/dashboard", detail:
 
       return results.rows
     },
+    { detail: { description: "Best performing new releases from the last 30 days with at least 3 benchmarks." } },
   )
 
   // ── Most Tested Games ─────────────────────────────────────────────
@@ -112,6 +114,7 @@ export const dashboardPublicRoutes = new Elysia({ prefix: "/dashboard", detail:
 
       return results.rows
     },
+    { detail: { description: "Games with the most benchmark entries, ordered by count descending." } },
   )
 
   // ── Recently Added Benchmarks ──────────────────────────────────────
@@ -139,6 +142,7 @@ export const dashboardPublicRoutes = new Elysia({ prefix: "/dashboard", detail:
 
       return results.rows
     },
+    { detail: { description: "Games with the most recently added benchmarks, ordered by latest entry date." } },
   )
 
   // ── Most Reported Games ────────────────────────────────────────────
@@ -164,4 +168,5 @@ export const dashboardPublicRoutes = new Elysia({ prefix: "/dashboard", detail:
 
       return results.rows
     },
+    { detail: { description: "Games with the most open reports against their performance entries." } },
   )

lib/api/game-stats.ts

@@ -368,5 +368,6 @@ export const gameStatsRoutes = new Elysia({ prefix: "/games", detail: { tags: ["
   },
   {
     params: t.Object({ gameId: t.String() }),
+    detail: { description: "Aggregated performance statistics for a game — boxplot, historical, upscaler stats, FPS ranges, device breakdown, and battery life estimates." },
   },
 )

lib/api/games-performance.ts

@@ -184,5 +184,6 @@ export const gamesPerformanceRoutes = new Elysia({
   },
   {
     params: t.Object({ gameId: t.String() }),
+    detail: { description: "Returns all non-removed performance presets for a game with user, hardware, platform support, and screenshot data. Ordered by pinned then upvotes." },
   },
 )

lib/api/mobile.ts

@@ -532,6 +532,19 @@ export const mobileRoutes = new Elysia({
   },
   {
     params: t.Object({ gameId: t.String() }),
+    response: t.Union([
+      t.Object({
+        game: t.Any(),
+        stats: t.Any(),
+        presets: t.Array(t.Any()),
+        platformSupport: t.Array(t.Any()),
+        comments: t.Object({
+          data: t.Array(t.Any()),
+          total: t.Number(),
+        }),
+      }),
+      t.Object({ error: t.String() }),
+    ]),
   },
 )
   // ── Mobile Search (DB-synced games only, no Steam results) ──────
@@ -692,6 +705,27 @@ export const mobileRoutes = new Elysia({
       detail: {
         description: "Search synced games only — returns mobile-optimized results with performance tags. No Steam-only entries.",
       },
+      response: t.Union([
+        t.Object({
+          results: t.Array(t.Object({
+            id: t.String(),
+            title: t.String(),
+            capsuleImage: t.Union([t.String(), t.Null()]),
+            headerImage: t.Union([t.String(), t.Null()]),
+            playabilityStatus: t.Union([t.String(), t.Null()]),
+            platformStatus: t.Union([t.String(), t.Null()]),
+            isRawPerformer: t.Boolean(),
+            isPoorPerformance: t.Boolean(),
+            bestFps: t.Union([t.Number(), t.Null()]),
+            estimatedBatteryMin: t.Union([t.Number(), t.Null()]),
+            benchmarkCount: t.Number(),
+            commentCount: t.Number(),
+            steamReviewScore: t.Union([t.Number(), t.Null()]),
+          })),
+          total: t.Number(),
+        }),
+        t.Object({ error: t.String() }),
+      ]),
     },
   )
   // ── Benchmark Detail (structured sections) ────────────────────
@@ -842,6 +876,20 @@ export const mobileRoutes = new Elysia({
       detail: {
         description: "Full benchmark entry detail with structured sections for mobile display — Performance, Hardware & Power, Software, and Game Info.",
       },
+      response: t.Union([
+        t.Object({
+          benchmark: t.Any(),
+          performance: t.Any(),
+          hardwarePower: t.Any(),
+          software: t.Any(),
+          gameInfo: t.Any(),
+          settingsJson: t.Union([t.Array(t.Any()), t.Null()]),
+          screenshots: t.Array(t.Any()),
+          youtubeVideoId: t.Union([t.String(), t.Null()]),
+          userNotes: t.Union([t.String(), t.Null()]),
+        }),
+        t.Object({ error: t.String() }),
+      ]),
     },
   )
   // ── Dashboard (consolidated home screen) ───────────────────────
@@ -909,5 +957,10 @@ export const mobileRoutes = new Elysia({
       detail: {
         description: "Consolidated home screen data — recent benchmarks, trending, and most tested in one call.",
       },
+      response: t.Object({
+        recentBenchmarks: t.Array(t.Any()),
+        trending: t.Array(t.Any()),
+        mostTested: t.Array(t.Any()),
+      }),
     },
   )

lib/api/search-unified.ts

@@ -528,5 +528,8 @@ export const searchUnifiedRoutes = new Elysia({ prefix: "/search", detail: { tag
       isFree: t.Optional(t.String()),
       hasMultiplayer: t.Optional(t.String()),
     }),
+    detail: {
+      description: "Unified search across local database and Steam store. Returns both synced games (with performance data) and Steam-only results.",
+    },
   },
 )