feat: automate OpenAPI spec sync with endpoint filtering

derrekcoleman · derrekcoleman · commit 07e2f1aa5d27 · 2025-11-26T11:53:03.000-07:00
Add sync-openapi.ts script that fetches upstream openapi.json from
js-recall main branch and filters it for public documentation.

Blocked path patterns:
- /api/admin/** (admin endpoints)
- /api/user/** (user dashboard endpoints)
- /api/auth/login (user login)
- /api/competitions/{id}/partners (partners listing)
- /nfl/** (NFL endpoints)

Blocked tags: Admin, User, NFL

Also injects missing security scheme definitions (AgentApiKey, bearerAuth)
until upstream fixes are merged.
diff --git a/docs/reference/endpoints/account.mdx b/docs/reference/endpoints/account.mdx
@@ -0,0 +1,14 @@
+---
+title: Account
+description: Account management endpoints
+full: true
+_openapi:
+  toc: []
+  structuredData:
+    headings: []
+    contents: []
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+<APIPage document={"specs/competitions.json"} operations={[]} webhooks={[]} hasHead={true} />
diff --git a/docs/reference/endpoints/agent.mdx b/docs/reference/endpoints/agent.mdx
@@ -1,6 +1,6 @@
 ---
 title: Agent
-description: Agent management endpoints for a single agent to interact with
+description: Agent management endpoints
 full: true
 _openapi:
   toc: []
diff --git a/docs/reference/endpoints/agents.mdx b/docs/reference/endpoints/agents.mdx
diff --git a/docs/reference/endpoints/arenas.mdx b/docs/reference/endpoints/arenas.mdx
diff --git a/docs/reference/endpoints/auth.mdx b/docs/reference/endpoints/auth.mdx
@@ -1,6 +1,6 @@
 ---
 title: Auth
-description: Authentication endpoints for verifying agent wallet ownership
+description: Authentication endpoints
 full: true
 _openapi:
   toc: []
diff --git a/docs/reference/endpoints/competition.mdx b/docs/reference/endpoints/competition.mdx
@@ -1,13 +1,16 @@
 ---
 title: Competition
-description: Get information about or interact with a competition
+description: Competition endpoints
 full: true
 _openapi:
   toc: []
   structuredData:
     headings: []
     contents:
       - content: Get all competitions
+      - content: >-
+          Get the competition rules including trading constraints, rate limits, and formulas for a
+          specific competition
       - content: >-
           Get detailed information about a specific competition including all metadata
       - content: >-
@@ -20,9 +23,6 @@ _openapi:
 
           while preserving historical participation data. Note: Cannot leave competitions that have
           already ended.
-      - content: >-
-          Get the competition rules including trading constraints, rate limits, and formulas for a
-          specific competition
       - content: Get the timeline for all agents in a competition
       - content: >-
           Get all trades for a specific competition. Only available for paper trading competitions.
@@ -50,11 +50,11 @@ _openapi:
   document={"specs/competitions.json"}
   operations={[
     { path: "/api/competitions", method: "get" },
+    { path: "/api/competitions/{competitionId}/rules", method: "get" },
     { path: "/api/competitions/{competitionId}", method: "get" },
     { path: "/api/competitions/{competitionId}/agents", method: "get" },
     { path: "/api/competitions/{competitionId}/agents/{agentId}", method: "post" },
     { path: "/api/competitions/{competitionId}/agents/{agentId}", method: "delete" },
-    { path: "/api/competitions/{competitionId}/rules", method: "get" },
     { path: "/api/competitions/{competitionId}/timeline", method: "get" },
     { path: "/api/competitions/{competitionId}/trades", method: "get" },
     { path: "/api/competitions/{competitionId}/agents/{agentId}/trades", method: "get" },
diff --git a/docs/reference/endpoints/health.mdx b/docs/reference/endpoints/health.mdx
@@ -1,6 +1,6 @@
 ---
 title: Health
-description: Health check endpoints to ensure the API is running
+description: Health check endpoints
 full: true
 _openapi:
   toc: []
diff --git a/docs/reference/endpoints/leaderboard.mdx b/docs/reference/endpoints/leaderboard.mdx
diff --git a/docs/reference/endpoints/price.mdx b/docs/reference/endpoints/price.mdx
@@ -1,6 +1,6 @@
 ---
 title: Price
-description: Price information endpoints for fetching token prices
+description: Price information endpoints
 full: true
 _openapi:
   method: GET
diff --git a/docs/reference/endpoints/trade.mdx b/docs/reference/endpoints/trade.mdx
@@ -1,6 +1,6 @@
 ---
 title: Trade
-description: Trading endpoints for executing trades as part of a competition
+description: Trading endpoints
 full: true
 _openapi:
   toc: []
diff --git a/scripts/sync-openapi.ts b/scripts/sync-openapi.ts
@@ -0,0 +1,82 @@
+import fs from "fs/promises";
+
+const SOURCE_URL =
+  "https://raw.githubusercontent.com/recallnet/js-recall/main/apps/api/openapi/openapi.json";
+const OUTPUT_PATH = "specs/competitions.json";
+
+const BLOCKED_PATH_PATTERNS = [
+  /^\/api\/admin\//,
+  /^\/api\/user\//,
+  /^\/api\/auth\/login$/,
+  /^\/api\/competitions\/[^/]+\/partners$/,
+  /^\/nfl\//,
+];
+
+const BLOCKED_TAGS = ["Admin", "User", "NFL"];
+
+function isPathBlocked(path: string): boolean {
+  return BLOCKED_PATH_PATTERNS.some((pattern) => pattern.test(path));
+}
+
+async function main(): Promise<void> {
+  console.log(`Fetching OpenAPI spec from ${SOURCE_URL}...`);
+
+  const response = await fetch(SOURCE_URL);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch: ${response.status} ${response.statusText}`);
+  }
+
+  const spec = await response.json();
+
+  const originalPaths = Object.keys(spec.paths);
+  const filteredPaths: Record<string, unknown> = {};
+
+  for (const [path, value] of Object.entries(spec.paths)) {
+    if (!isPathBlocked(path)) {
+      filteredPaths[path] = value;
+    }
+  }
+
+  spec.paths = filteredPaths;
+
+  const removedPathCount = originalPaths.length - Object.keys(filteredPaths).length;
+  console.log(`Filtered ${removedPathCount} blocked endpoints (${Object.keys(filteredPaths).length} remaining)`);
+
+  if (spec.tags) {
+    const originalTagCount = spec.tags.length;
+    spec.tags = spec.tags.filter(
+      (tag: { name: string }) => !BLOCKED_TAGS.includes(tag.name)
+    );
+    console.log(`Filtered ${originalTagCount - spec.tags.length} blocked tags`);
+  }
+
+  spec.components ??= {};
+  spec.components.securitySchemes ??= {};
+
+  // Upstream uses AgentApiKey in /api/auth/* endpoints but doesn't define it.
+  // Inject the definition if missing. Remove this block once upstream defines AgentApiKey.
+  if (!spec.components.securitySchemes.AgentApiKey) {
+    spec.components.securitySchemes.AgentApiKey = {
+      type: "http",
+      scheme: "bearer",
+      description: "Agent API key provided as Bearer token",
+    };
+    console.log("Injected missing AgentApiKey security scheme");
+  }
+
+  // Upstream uses bearerAuth (lowercase) in some endpoints but doesn't define it.
+  // Inject the definition if missing. Remove this block once upstream defines bearerAuth.
+  if (!spec.components.securitySchemes.bearerAuth) {
+    spec.components.securitySchemes.bearerAuth = {
+      type: "http",
+      scheme: "bearer",
+      description: "Bearer token authentication",
+    };
+    console.log("Injected missing bearerAuth security scheme");
+  }
+
+  await fs.writeFile(OUTPUT_PATH, JSON.stringify(spec, null, 2) + "\n");
+  console.log(`Written to ${OUTPUT_PATH}`);
+}
+
+void main();
diff --git a/specs/competitions.json b/specs/competitions.json
