feat(ensapi): add openapi

.changeset/vast-parents-roll.md

@@ -0,0 +1,6 @@
+---
+"@ensnode/ensnode-sdk": patch
+"ensapi": patch
+---
+
+Adds OpenAPI schema endpoint and route descriptions to ENSApi

apps/ensapi/package.json

@@ -27,6 +27,7 @@
     "@ensnode/ponder-subgraph": "workspace:*",
     "@hono/node-server": "^1.19.5",
     "@hono/otel": "^0.2.2",
+    "@hono/standard-validator": "^0.2.0",
     "@hono/zod-validator": "^0.7.2",
     "@namehash/ens-referrals": "workspace:*",
     "@opentelemetry/api": "^1.9.0",
@@ -40,9 +41,11 @@
     "@opentelemetry/sdk-trace-node": "^2.0.1",
     "@opentelemetry/semantic-conventions": "^1.34.0",
     "@ponder/utils": "catalog:",
+    "@standard-schema/utils": "^0.3.0",
     "date-fns": "catalog:",
     "drizzle-orm": "catalog:",
     "hono": "catalog:",
+    "hono-openapi": "^1.1.1",
     "p-memoize": "^8.0.0",
     "p-retry": "^7.1.0",
     "pg-connection-string": "catalog:",

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

@@ -1,12 +1,18 @@
 import config from "@/config";
 
+import { describeRoute, resolver as validationResolver } from "hono-openapi";
+
 import {
   IndexingStatusResponseCodes,
   type IndexingStatusResponseError,
   type IndexingStatusResponseOk,
   serializeENSApiPublicConfig,
   serializeIndexingStatusResponse,
 } from "@ensnode/ensnode-sdk";
+import {
+  makeENSApiPublicConfigSchema,
+  makeIndexingStatusResponseSchema,
+} from "@ensnode/ensnode-sdk/internal";
 
 import { buildEnsApiPublicConfig } from "@/config/config.schema";
 import { factory } from "@/lib/hono-factory";
@@ -17,36 +23,76 @@ import resolutionApi from "./resolution-api";
 
 const app = factory.createApp();
 
-// include ENSApi Public Config endpoint
-app.get("/config", async (c) => {
-  const ensApiPublicConfig = buildEnsApiPublicConfig(config);
-  return c.json(serializeENSApiPublicConfig(ensApiPublicConfig));
-});
+app.get(
+  "/config",
+  describeRoute({
+    summary: "Get ENSApi Public Config",
+    description: "Gets the public config of the ENSApi instance",
+    responses: {
+      200: {
+        description: "Successfully retrieved ENSApi public config",
+        content: {
+          "application/json": {
+            schema: validationResolver(makeENSApiPublicConfigSchema()),
+          },
+        },
+      },
+    },
+  }),
+  async (c) => {
+    const ensApiPublicConfig = buildEnsApiPublicConfig(config);
+    return c.json(serializeENSApiPublicConfig(ensApiPublicConfig));
+  },
+);
+
+app.get(
+  "/indexing-status",
+  describeRoute({
+    summary: "Get ENSIndexer Indexing Status",
+    description: "Returns the indexing status snapshot most recently captured from ENSIndexer",
+    responses: {
+      200: {
+        description: "Successfully retrieved indexing status",
+        content: {
+          "application/json": {
+            schema: validationResolver(makeIndexingStatusResponseSchema()),
+          },
+        },
+      },
+      503: {
+        description: "Indexing status snapshot unavailable",
+        content: {
+          "application/json": {
+            schema: validationResolver(makeIndexingStatusResponseSchema()),
+          },
+        },
+      },
+    },
+  }),
+  async (c) => {
+    // context must be set by the required middleware
+    if (c.var.indexingStatus === undefined) {
+      throw new Error(`Invariant(indexing-status): indexingStatusMiddleware required`);
+    }
 
-// include ENSIndexer Indexing Status endpoint
-app.get("/indexing-status", async (c) => {
-  // context must be set by the required middleware
-  if (c.var.indexingStatus === undefined) {
-    throw new Error(`Invariant(ensnode-api): indexingStatusMiddleware required`);
-  }
+    if (c.var.indexingStatus instanceof Error) {
+      return c.json(
+        serializeIndexingStatusResponse({
+          responseCode: IndexingStatusResponseCodes.Error,
+        } satisfies IndexingStatusResponseError),
+        503,
+      );
+    }
 
-  if (c.var.indexingStatus instanceof Error) {
+    // return successful response using the indexing status projection from the middleware context
     return c.json(
       serializeIndexingStatusResponse({
-        responseCode: IndexingStatusResponseCodes.Error,
-      } satisfies IndexingStatusResponseError),
-      503,
+        responseCode: IndexingStatusResponseCodes.Ok,
+        realtimeProjection: c.var.indexingStatus,
+      } satisfies IndexingStatusResponseOk),
     );
-  }
-
-  // return successful response using the indexing status projection from the context
-  return c.json(
-    serializeIndexingStatusResponse({
-      responseCode: IndexingStatusResponseCodes.Ok,
-      realtimeProjection: c.var.indexingStatus,
-    } satisfies IndexingStatusResponseOk),
-  );
-});
+  },
+);
 
 // Name Tokens API
 app.route("/name-tokens", nameTokensApi);