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

.github/workflows/test_ci.yml

@@ -48,7 +48,46 @@
       - 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: Start ENSApi in OpenAPI CI check mode
+        run: |
+          OPENAPI_CI_CHECK=true pnpm --filter ensapi start &
+          # Wait for server to be ready
+          for i in {1..30}; do
+            if curl -s http://localhost:4334/openapi.json > /dev/null 2>&1; then
+              echo "ENSApi is ready"
+              break
+            fi
+            echo "Waiting for ENSApi to start... ($i/30)"
+            sleep 1
+          done
+
+      - name: Generate OpenAPI spec from local build
+        working-directory: docs/docs.ensnode.io
+        run: pnpm openapi:generate http://localhost:4334
+
+      - name: Verify OpenAPI spec matches committed version
+        run: |
+          if git diff --quiet docs/docs.ensnode.io/openapi.json; then
+            echo "✅ OpenAPI spec is in sync with codebase"
+          else
+            echo "❌ OpenAPI spec is out of sync"
+            echo ""
+            echo "The committed openapi.json differs from what ENSApi generates:"
+            echo ""
+            git diff --color docs/docs.ensnode.io/openapi.json
+            echo ""
+            echo "Run 'OPENAPI_CI_CHECK=true pnpm --filter ensapi start' then 'pnpm --filter @docs/mintlify openapi:generate http://localhost:4334' and commit the changes."
+            exit 1
+          fi
+
   integrity-check:
     name: "Integrity Check"
     runs-on: blacksmith-4vcpu-ubuntu-2204
     services:

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

@@ -76,13 +76,68 @@ const EnsApiConfigSchema = z
 
 export type EnsApiConfig = z.infer<typeof EnsApiConfigSchema>;
 
+const EnsApiConfigSchemaForOpenApiCiCheck = z.object({
+  port: PortSchema.default(ENSApi_DEFAULT_PORT),
+  databaseUrl: DatabaseUrlSchema,
+  databaseSchemaName: DatabaseSchemaNameSchema,
+  ensIndexerUrl: EnsIndexerUrlSchema,
+  theGraphApiKey: TheGraphApiKeySchema,
+  namespace: ENSNamespaceSchema,
+  rpcConfigs: RpcConfigsSchema,
+  ensIndexerPublicConfig: makeENSIndexerPublicConfigSchema("ensIndexerPublicConfig"),
+  ensHolidayAwardsStart: z.number(),
+  ensHolidayAwardsEnd: z.number(),
+});
+
+function buildConfigForOpenApiCiCheck(env: EnsApiEnvironment): EnsApiConfig {
+  logger.info("OPENAPI_CI_CHECK mode enabled - using minimal mock config");
+
+  return EnsApiConfigSchemaForOpenApiCiCheck.parse({
+    port: env.PORT || ENSApi_DEFAULT_PORT,
+    databaseUrl: "postgresql://openapi:openapi@localhost:5432/openapi",
+    databaseSchemaName: "public",
+    ensIndexerUrl: "http://localhost:42069",
+    theGraphApiKey: undefined,
+    namespace: "mainnet",
+    rpcConfigs: {
+      "1": "https://rpc.example.com",
+    },
+    ensIndexerPublicConfig: {
+      labelSet: {
+        labelSetId: "ens-default",
+        labelSetVersion: 1,
+      },
+      indexedChainIds: [1],
+      isSubgraphCompatible: false,
+      namespace: "mainnet",
+      plugins: ["subgraph"],
+      databaseSchemaName: "public",
+      versionInfo: {
+        nodejs: process.version,
+        ponder: "0.0.0",
+        ensDb: packageJson.version,
+        ensIndexer: packageJson.version,
+        ensNormalize: "0.0.0",
+        ensRainbow: packageJson.version,
+        ensRainbowSchema: 1,
+      },
+    },
+    ensHolidayAwardsStart: getUnixTime(new Date(ENS_HOLIDAY_AWARDS_START_DATE)),
+    ensHolidayAwardsEnd: getUnixTime(new Date(ENS_HOLIDAY_AWARDS_END_DATE)),
+  }) as EnsApiConfig;
+}
+
 /**
  * Builds the EnsApiConfig from an EnsApiEnvironment object, fetching the EnsIndexerPublicConfig.
  *
  * @returns A validated EnsApiConfig object
  * @throws Error with formatted validation messages if environment parsing fails
  */
 export async function buildConfigFromEnvironment(env: EnsApiEnvironment): Promise<EnsApiConfig> {
+  if (env.OPENAPI_CI_CHECK === "true") {
+    return buildConfigForOpenApiCiCheck(env);
+  }
+
   try {
     const ensIndexerUrl = EnsIndexerUrlSchema.parse(env.ENSINDEXER_URL);
 

apps/ensapi/src/config/environment.ts

@@ -21,4 +21,6 @@ export type EnsApiEnvironment = Omit<DatabaseEnvironment, "DATABASE_SCHEMA"> &
   PortEnvironment &
   LogLevelEnvironment &
   TheGraphEnvironment &
-  EnsHolidayAwardsEnvironment;
+  EnsHolidayAwardsEnvironment & {
+    OPENAPI_CI_CHECK?: string;
+  };

apps/ensapi/src/handlers/ensanalytics-api.ts

@@ -53,7 +53,7 @@ const app = factory
   .get(
     "/referrers",
     describeRoute({
-      tags: ["ENSAwards"],
+      tags: ["ENSAwardsssss"],
       summary: "Get Referrer Leaderboard",
       description: "Returns a paginated page from the referrer leaderboard",
       responses: {

docs/docs.ensnode.io/README.md

@@ -2,34 +2,61 @@
 
 [docs.ensnode.io](https://docs.ensnode.io) runs on [Mintlify](https://mintlify.com).
 
-## Local Development
+Learn more about [ENSNode](https://ensnode.io) from [the "Starlight" ENSNode docs](https://ensnode.io/docs/). Everything from these "Starlight" docs is planned to be transitioned into these Mintlify docs soon.
 
-### Getting Started
+## API Docs
+
+This Mintlify site serves two (potentially distinct) sets of API docs from two sources:
+
+| Section              | Source             | Purpose                                     |
+| -------------------- | ------------------ | ------------------------------------------- |
+| **API Reference**    | Production API URL | Always reflects the live deployed API       |
+| **Preview** (hidden) | `./openapi.json`   | PR preview deployments for upcoming changes |
+
+When you change API routes or schemas, update the committed `openapi.json` to preview changes in Mintlify's PR deployments.
+
+## OpenAPI Spec Management
+
+We use a combination of runtime URLs and committed files to keep API docs in sync across environments. This setup achieves:
 
-1. Clone the repository:
+- Production API docs match the production deployment, even when production lags behind `main`
+- Non-API docs stay in sync with `main` through normal Git flow
+- Each branch has its own `openapi.json`, validated by the CI to be in sync with the `openapi.json` that would actually be returned by the code for ENSApi in the same branch.
+- PR previews show upcoming API changes before merge
 
-   ```bash
-   git clone https://github.com/namehash/ensnode.git
-   ```
+### Generating the Spec
 
-2. Navigate to the docs directory:
+To generate the OpenAPI spec, you need a running ENSApi instance. For local development without external dependencies, use the `OPENAPI_CI_CHECK` mode:
 
-   ```bash
-   cd ensnode/docs/docs.ensnode.io
-   ```
+```bash
+# Start ENSApi in CI check mode (no external dependencies required)
+OPENAPI_CI_CHECK=true pnpm --filter ensapi start
 
-3. Start the local development server:
+# In another terminal, generate the spec
+pnpm --filter docs.ensnode.io openapi:generate http://localhost:4334
+```
 
-   ```bash
-   pnpm mint dev
-   ```
+The URL argument is required — there is no default to avoid accidentally generating from the wrong source.
+
+### CI Validation
+
+CI runs an `openapi-sync-check` job that starts ENSApi in `OPENAPI_CI_CHECK` mode and compares the generated spec against the committed `openapi.json`. If they differ, the check fails.
+
+Update the committed spec when you've changed API routes or schemas.
+
+## Local Development
+
+### Getting Started
 
+1. `git clone https://github.com/namehash/ensnode.git`
+2. `cd docs/docs.ensnode.io`
+3. `pnpm mint dev`
 4. Open [http://localhost:3000](http://localhost:3000) in your browser
 
 ### Troubleshooting
 
-- If a page loads as a 404, make sure you are running in a folder with a valid `docs.json`.
-- Run `pnpm mint --help` to read more details about Mintlify CLI.
+- If a page loads as a 404, ensure you're running in a folder with a valid `docs.json`
+- Run `pnpm mint --help` for more Mintlify CLI details
 
 ## Publishing Changes
 
@@ -38,3 +65,4 @@ Changes pushed to the main branch are automatically deployed to production.
 ## Resources
 
 - [Mintlify documentation](https://mintlify.com/docs)
+- [ENSNode "Starlight" docs](https://ensnode.io/docs/)

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).