feat(docs): OpenAPI spec sync with CI validation and PR previews

.changeset/bright-waves-flow.md

@@ -0,0 +1,5 @@
+---
+"@docs/mintlify": patch
+---
+
+Introduce API documentation for ENSApi that's generated automatically from the OpenAPI spec

.changeset/gentle-clouds-dance.md

@@ -0,0 +1,5 @@
+---
+"ensapi": patch
+---
+
+Add `OPENAPI_GENERATE_MODE` environment variable to enable starting ENSApi with a mock config exclusively for OpenAPI spec generation without external dependencies

.github/scripts/generate_openapi_spec.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+
+# Generate OpenAPI spec from ENSApi
+# This script can be used both locally and in CI
+#
+# Usage:
+#   ./generate_openapi_spec.sh           # Generate spec (default)
+#   ./generate_openapi_spec.sh --check   # Generate and verify against committed version
+#
+# Environment variables:
+#   ENSAPI_PORT        - Port for ENSApi (default: 4334)
+#   STARTUP_TIMEOUT    - Seconds to wait for server startup (default: 30)
+#   SKIP_VALIDATION    - Set to "true" to skip Mintlify validation (default: false)
+
+set -e
+
+# Configuration
+ENSAPI_PORT="${ENSAPI_PORT:-4334}"
+STARTUP_TIMEOUT="${STARTUP_TIMEOUT:-30}"
+SKIP_VALIDATION="${SKIP_VALIDATION:-false}"
+ENSAPI_URL="http://localhost:${ENSAPI_PORT}"
+
+# Parse arguments
+CHECK_MODE=false
+for arg in "$@"; do
+  case $arg in
+    --check)
+      CHECK_MODE=true
+      shift
+      ;;
+  esac
+done
+
+# Detect repository root
+if [ -n "$GITHUB_WORKSPACE" ]; then
+  REPO_ROOT="$GITHUB_WORKSPACE"
+else
+  SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+  REPO_ROOT="$( cd "$SCRIPT_DIR/../.." && pwd )"
+fi
+
+OPENAPI_JSON="$REPO_ROOT/docs/docs.ensnode.io/openapi.json"
+ENSAPI_PID=""
+
+# Cleanup function
+cleanup() {
+  if [ -n "$ENSAPI_PID" ]; then
+    echo "Stopping ENSApi (PID: $ENSAPI_PID)..."
+    kill "$ENSAPI_PID" 2>/dev/null || true
+    wait "$ENSAPI_PID" 2>/dev/null || true
+  fi
+}
+
+trap cleanup EXIT INT TERM
+
+echo "Starting ENSApi in OpenAPI generate mode..."
+
+# Start ENSApi in background
+cd "$REPO_ROOT"
+OPENAPI_GENERATE_MODE=true pnpm --filter ensapi start &
+ENSAPI_PID=$!
+
+# Wait for server to be ready
+echo "Waiting for ENSApi to start (timeout: ${STARTUP_TIMEOUT}s)..."
+SERVER_READY=false
+for i in $(seq 1 "$STARTUP_TIMEOUT"); do
+  if curl --fail --silent --max-time 5 "${ENSAPI_URL}/openapi.json" > /dev/null 2>&1; then
+    echo "ENSApi is ready and responding"
+    SERVER_READY=true
+    break
+  fi
+
+  # Check if the process is still running
+  if ! kill -0 "$ENSAPI_PID" 2>/dev/null; then
+    echo "Error: ENSApi process exited unexpectedly"
+    exit 1
+  fi
+
+  echo "Waiting for ENSApi to start... ($i/$STARTUP_TIMEOUT)"
+  sleep 1
+done
+
+if [ "$SERVER_READY" != "true" ]; then
+  echo "Error: ENSApi failed to start within ${STARTUP_TIMEOUT} seconds"
+  exit 1
+fi
+
+# Generate the OpenAPI spec
+echo "Generating OpenAPI spec..."
+pnpm --filter @docs/mintlify openapi:generate "$ENSAPI_URL"
+
+# Stop the server now that we have the spec
+echo "Stopping ENSApi..."
+kill "$ENSAPI_PID" 2>/dev/null || true
+wait "$ENSAPI_PID" 2>/dev/null || true
+ENSAPI_PID=""
+
+# Check mode: verify spec matches committed version
+if [ "$CHECK_MODE" = "true" ]; then
+  echo "Verifying OpenAPI spec matches committed version..."
+  if git diff --quiet "$OPENAPI_JSON"; then
+    echo "OpenAPI spec is in sync with codebase"
+  else
+    echo "Error: OpenAPI spec is out of sync"
+    echo ""
+    echo "The committed openapi.json differs from what ENSApi generates:"
+    echo ""
+    git diff --color "$OPENAPI_JSON"
+    echo ""
+    echo "To fix, run: ./.github/scripts/generate_openapi_spec.sh"
+    echo "Then commit the updated openapi.json."
+    exit 1
+  fi
+fi
+
+# Validate with Mintlify (unless skipped)
+if [ "$SKIP_VALIDATION" != "true" ]; then
+  echo "Validating OpenAPI spec with Mintlify..."
+  pnpm dlx mintlify openapi-check "$OPENAPI_JSON"
+fi
+
+echo "Done!"

.github/workflows/deploy_switch_ensnode_environment.yml

@@ -94,6 +94,111 @@ jobs:
           chmod +x ./.github/scripts/promote_ensadmin.sh
           ./.github/scripts/promote_ensadmin.sh
 
+      - name: Trigger Mintlify Docs Rebuild
+        id: mintlify_rebuild
+        # Non-blocking: failures are reported to Slack and can be manually retriggered
+        continue-on-error: true
+        env:
+          MINTLIFY_API_TOKEN: ${{ secrets.MINTLIFY_API_TOKEN }}
+          MINTLIFY_PROJECT_ID: ${{ vars.MINTLIFY_PROJECT_ID }}
+        run: |
+          # Trigger the rebuild and capture the statusId
+          HTTP_RESPONSE=$(curl --silent --write-out "\n%{http_code}" \
+            --connect-timeout 10 \
+            --max-time 30 \
+            --retry 2 \
+            --retry-delay 5 \
+            --request POST \
+            --url "https://api.mintlify.com/v1/project/update/${MINTLIFY_PROJECT_ID}" \
+            --header "Authorization: Bearer ${MINTLIFY_API_TOKEN}")
+
+          HTTP_BODY=$(echo "$HTTP_RESPONSE" | sed '$d')
+          HTTP_CODE=$(echo "$HTTP_RESPONSE" | tail -n1)
+
+          if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
+            echo "Mintlify API returned HTTP $HTTP_CODE"
+            echo "Response body: $HTTP_BODY"
+            exit 1
+          fi
+
+          echo "Mintlify rebuild triggered successfully (HTTP $HTTP_CODE)"
+
+          # Extract statusId from response
+          STATUS_ID=$(echo "$HTTP_BODY" | jq -r '.statusId // empty')
+          if [ -z "$STATUS_ID" ]; then
+            echo "Failed to extract statusId from response"
+            echo "Response body: $HTTP_BODY"
+            exit 1
+          fi
+
+          echo "Status ID: $STATUS_ID"
+
+          # Poll for completion (max 5 minutes, checking every 10 seconds)
+          MAX_ATTEMPTS=30
+          ATTEMPT=0
+
+          while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do
+            ATTEMPT=$((ATTEMPT + 1))
+            echo "Checking status (attempt $ATTEMPT/$MAX_ATTEMPTS)..."
+
+            STATUS_RESPONSE=$(curl --silent --write-out "\n%{http_code}" \
+              --connect-timeout 10 \
+              --max-time 30 \
+              --request GET \
+              --url "https://api.mintlify.com/v1/project/update-status/${STATUS_ID}" \
+              --header "Authorization: Bearer ${MINTLIFY_API_TOKEN}")
+
+            STATUS_BODY=$(echo "$STATUS_RESPONSE" | sed '$d')
+            STATUS_CODE=$(echo "$STATUS_RESPONSE" | tail -n1)
+
+            if [ "$STATUS_CODE" -lt 200 ] || [ "$STATUS_CODE" -ge 300 ]; then
+              echo "Status check failed with HTTP $STATUS_CODE"
+              echo "Response: $STATUS_BODY"
+              sleep 10
+              continue
+            fi
+
+            STATUS=$(echo "$STATUS_BODY" | jq -r '.status // empty')
+            echo "Current status: $STATUS"
+
+            case "$STATUS" in
+              "success")
+                echo "Mintlify docs rebuild completed successfully"
+                exit 0
+                ;;
+              "failure")
+                echo "Mintlify docs rebuild failed"
+                exit 1
+                ;;
+              "queued"|"in_progress")
+                sleep 10
+                ;;
+              *)
+                echo "Unknown status: $STATUS"
+                sleep 10
+                ;;
+            esac
+          done
+
+          echo "Timeout waiting for Mintlify rebuild to complete"
+          exit 1
+
+      - name: Notify Mintlify Rebuild Failure
+        if: steps.mintlify_rebuild.outcome == 'failure'
+        uses: ./.github/actions/send_slack_notification
+        with:
+          slack_webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          slack_title: "Mintlify Docs Rebuild Failed"
+          slack_message: "Mintlify docs rebuild failed during environment switch to ${{ inputs.target }}. Check the workflow logs for details."
+
+      - name: Notify Mintlify Rebuild Success
+        if: steps.mintlify_rebuild.outcome == 'success'
+        uses: ./.github/actions/send_slack_notification
+        with:
+          slack_webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          slack_title: "Mintlify Docs Rebuilt"
+          slack_message: "Mintlify docs successfully rebuilt for environment switch to ${{ inputs.target }}. API Reference built from: https://api.alpha.ensnode.io/openapi.json"
+
       - name: Send Slack Notification
         uses: ./.github/actions/send_slack_notification
         with:

.github/workflows/test_ci.yml

@@ -48,7 +48,16 @@
       - 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 and verify OpenAPI spec
+        run: ./.github/scripts/generate_openapi_spec.sh --check
+
   integrity-check:
     name: "Integrity Check"
     runs-on: blacksmith-4vcpu-ubuntu-2204
     services:

apps/ensapi/.env.local.example

@@ -119,3 +119,24 @@ DATABASE_URL=postgresql://dbuser:abcd1234@localhost:5432/my_database
 # Note: ENS_HOLIDAY_AWARDS_START date must be before or the same as ENS_HOLIDAY_AWARDS_END
 # ENS_HOLIDAY_AWARDS_START="2025-12-01T00:00:00Z"
 # ENS_HOLIDAY_AWARDS_END="2025-12-31T23:59:59Z"
+
+# OpenAPI Generate Mode
+# Optional. When set to "true", ENSApi starts with a minimal mock configuration,
+# bypassing the need for a real database, ENSIndexer, or RPC connections.
+# This is useful for generating the OpenAPI spec without external dependencies.
+#
+# When enabled:
+# - All routes return HTTP 503 Service Unavailable EXCEPT for /openapi.json
+# - The following environment variables are IGNORED (mock values are used instead):
+#   - DATABASE_URL
+#   - ENSINDEXER_URL
+#   - THEGRAPH_API_KEY
+#   - All RPC configuration variables (ALCHEMY_API_KEY, QUICKNODE_API_KEY,
+#     QUICKNODE_ENDPOINT_NAME, DRPC_API_KEY, RPC_URL_*)
+#   - ENS_HOLIDAY_AWARDS_START
+#   - ENS_HOLIDAY_AWARDS_END
+# - The following environment variables are still respected:
+#   - PORT
+#   - LOG_LEVEL
+#
+# OPENAPI_GENERATE_MODE=true

apps/ensapi/src/config/config.schema.test.ts

@@ -21,6 +21,8 @@ import logger from "@/lib/logger";
 vi.mock("@/lib/logger", () => ({
   default: {
     error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
   },
 }));
 
@@ -58,6 +60,28 @@ describe("buildConfigFromEnvironment", () => {
     mockFetch.mockReset();
   });
 
+  it("returns mock config without fetching when OPENAPI_GENERATE_MODE is enabled", async () => {
+    const result = await buildConfigFromEnvironment({
+      OPENAPI_GENERATE_MODE: "true",
+      PORT: "5000",
+    });
+
+    expect(mockFetch).not.toHaveBeenCalled();
+    expect(result.port).toBe(5000);
+    expect(result.namespace).toBe("mainnet");
+  });
+
+  it("logs warning when OPENAPI_GENERATE_MODE has invalid value", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve(serializeENSIndexerPublicConfig(ENSINDEXER_PUBLIC_CONFIG)),
+    });
+
+    await buildConfigFromEnvironment({ ...BASE_ENV, OPENAPI_GENERATE_MODE: "false" });
+
+    expect(logger.warn).toHaveBeenCalled();
+  });
+
   it("returns a valid config object using environment variables", async () => {
     mockFetch.mockResolvedValueOnce({
       ok: true,
@@ -84,6 +108,7 @@ describe("buildConfigFromEnvironment", () => {
       ]),
       ensHolidayAwardsStart: ENS_HOLIDAY_AWARDS_START_DATE,
       ensHolidayAwardsEnd: ENS_HOLIDAY_AWARDS_END_DATE,
+      inOpenApiGenerateMode: false,
     });
   });
 
@@ -166,6 +191,7 @@ describe("buildEnsApiPublicConfig", () => {
       ]),
       ensHolidayAwardsStart: ENS_HOLIDAY_AWARDS_START_DATE,
       ensHolidayAwardsEnd: ENS_HOLIDAY_AWARDS_END_DATE,
+      inOpenApiGenerateMode: false,
     };
 
     const result = buildEnsApiPublicConfig(mockConfig);
@@ -191,6 +217,7 @@ describe("buildEnsApiPublicConfig", () => {
       rpcConfigs: new Map(),
       ensHolidayAwardsStart: ENS_HOLIDAY_AWARDS_START_DATE,
       ensHolidayAwardsEnd: ENS_HOLIDAY_AWARDS_END_DATE,
+      inOpenApiGenerateMode: false,
     };
 
     const result = buildEnsApiPublicConfig(mockConfig);
@@ -227,6 +254,7 @@ describe("buildEnsApiPublicConfig", () => {
       ensHolidayAwardsStart: ENS_HOLIDAY_AWARDS_START_DATE,
       ensHolidayAwardsEnd: ENS_HOLIDAY_AWARDS_END_DATE,
       theGraphApiKey: "secret-api-key",
+      inOpenApiGenerateMode: false,
     };
 
     const result = buildEnsApiPublicConfig(mockConfig);