openapi spec / docs poc

.github/workflows/test_ci.yml

@@ -48,7 +48,32 @@
       - uses: ./.github/actions/setup_node_environment
       - run: pnpm test
 
+  openapi-sync-check:
+    name: "OpenAPI Spec Sync Check"
+    runs-on: blacksmith-4vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup_node_environment
+
+      - name: Generate OpenAPI spec from production
+        run: pnpm --filter ensapi openapi:generate
+
+      - name: Format generated spec with Biome
+        run: pnpm biome format --write docs/docs.ensnode.io/openapi.json
+
+      - name: Verify OpenAPI spec matches production
+        run: |
+          if git diff --exit-code docs/docs.ensnode.io/openapi.json; then
+            echo "✅ OpenAPI spec is in sync with production"
+          else
+            echo "❌ OpenAPI spec is out of sync with production"
+            echo ""
+            echo "The committed openapi.json differs from the production API."
+            echo "Run 'pnpm --filter ensapi openapi:generate' and commit the changes."
+            exit 1
+          fi
+
   integrity-check:
     name: "Integrity Check"
     runs-on: blacksmith-4vcpu-ubuntu-2204
     services:

apps/ensapi/package.json

@@ -17,7 +17,8 @@
     "test": "vitest",
     "lint": "biome check --write .",
     "lint:ci": "biome ci",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "openapi:generate": "tsx scripts/generate-openapi.ts"
   },
   "dependencies": {
     "@ensdomains/ensjs": "^4.0.2",

apps/ensapi/scripts/generate-openapi.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+
+/**
+ * Generate OpenAPI spec from a running ENSApi instance.
+ *
+ * Usage:
+ *   pnpm openapi:generate                           # Uses default URL (production)
+ *   pnpm openapi:generate http://localhost:3223     # Uses custom URL
+ *   ENSAPI_URL=http://localhost:3223 pnpm openapi:generate
+ *
+ * Output:
+ *   Writes openapi.json to the docs directory for Mintlify to consume.
+ *   Run `pnpm biome format --write docs/docs.ensnode.io/openapi.json` after to format.
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const DEFAULT_ENSAPI_URL = "https://api.alpha.ensnode.io";
+const OUTPUT_PATH = resolve(import.meta.dirname, "../../../docs/docs.ensnode.io/openapi.json");
+
+async function main() {
+  // Get URL from argument or environment variable
+  const ensapiUrl = process.argv[2] || process.env.ENSAPI_URL || DEFAULT_ENSAPI_URL;
+  const openapiUrl = `${ensapiUrl}/openapi.json`;
+
+  console.log(`Fetching OpenAPI spec from: ${openapiUrl}`);
+
+  const response = await fetch(openapiUrl);
+
+  if (!response.ok) {
+    console.error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`);
+    process.exit(1);
+  }
+
+  const spec = await response.json();
+
+  // Pretty-print the JSON for readability in git diffs
+  const content = `${JSON.stringify(spec, null, 2)}\n`;
+
+  writeFileSync(OUTPUT_PATH, content, "utf-8");
+
+  console.log(`OpenAPI spec written to: ${OUTPUT_PATH}`);
+  console.log(`Spec version: ${spec.info?.version}`);
+  console.log(`Paths: ${Object.keys(spec.paths || {}).length}`);
+}
+
+main().catch((error) => {
+  console.error("Error generating OpenAPI spec:", error);
+  process.exit(1);
+});

docs/docs.ensnode.io/docs.json

@@ -24,7 +24,13 @@
               },
               {
                 "group": "API Reference",
-                "openapi": "https://gist.githubusercontent.com/notrab/94b637e77468cbddd895d7933ce88f64/raw/12cb5ed183558a9bdda5d1c7004db6c794dbd13e/green-ensnode-openapi.json"
+                "openapi": "https://api.alpha.ensnode.io/openapi.json"
+              },
+              {
+                "group": "Preview",
+                "pages": ["ensapi/preview"],
+                "openapi": "./openapi.json",
+                "hidden": true
               }
             ]
           }

docs/docs.ensnode.io/ensapi/preview.mdx

@@ -0,0 +1,9 @@
+---
+title: API Preview
+sidebarTitle: Preview
+description: Preview upcoming API changes from the current branch.
+---
+
+This page shows the OpenAPI specification from the current branch, which may include unreleased API changes.
+
+For the production API documentation, see the [API Reference](/ensapi).