feat(ensapi): add openapi

[stevedylandev]

Summary

This PR starts implementation of hono-openapi to complete #1115. Work includes:

• Installing hono-openapi
• Updates validate.ts to use validator from hono-openapi
• Adds response zod schemas to ensnode-sdk
• Adds describeRoute to resolution endpoints
• Adds GET /openapi.json route

The result is an OpenAPI schema that can be fetched from /openapi.json from the ENSApi:

curl http://localhost:4334/openapi.json | jq . 

With the schema we can build new documentation that accepts OpenAPI for automatic API references. At least for the API we can write almost all of the documentation inside the routes themselves. Here is an example:

app.get(
  "/records/:name",
  describeRoute({
    summary: "Resolve ENS Records",
    description: `Resolves ENS records for a given name, including addresses, text records, and other metadata.

## Query Parameters

- \`addresses\` - Comma-separated list of coin type IDs (e.g., \`60\` for ETH, \`0\` for BTC)
- \`texts\` - Comma-separated list of text record keys (e.g., \`avatar\`, \`com.twitter\`)
- \`name\` - Set to \`true\` to include name resolution
- \`trace\` - Set to \`true\` to include resolution trace information
- \`accelerate\` - Set to \`true\` to attempt real-time acceleration

## Examples

### Resolve address records (ETH and BTC)
\`\`\`
GET /records/example.eth?addresses=60,0
\`\`\`

### Resolve text records (avatar and Twitter)
\`\`\`
GET /records/example.eth?texts=avatar,com.twitter
\`\`\`

### Combined resolution
\`\`\`
GET /records/example.eth?name=true&addresses=60,0&texts=avatar,com.twitter
\`\`\``,
    responses: {
      200: {
        description: "Successfully resolved records",
        content: {
          "application/json": {
            schema: resolver(makeResolveRecordsResponseSchema()),
          },
        },
      },
    },
  }),

Note

I don't like escaping characters in the mark up so I will be looking into another way to do this

This results in a docs page like this:

Take a look at the current preview built in a separate repo: https://docs-sepia-eight.vercel.app/docs/getApiResolveRecords

Testing

At the moment there isn't a clear way to make a unit test of the ENSApi src/index.ts. The following steps can be taken to test /openapi.json:

• Build and run the local Docker image

  pnpm run docker:build:ensnode
  docker compose up -d

• cURL the ENSApi endpoint for /openapi.json

  curl http://localhost:4334/openapi.json
  # Optionally pipe into jq for better formatting
  curl http://localhost:4334/openapi.json | jq .

Tested and validated 2025-12-30T15:04:07.424Z

[changeset-bot]

🦋 Changeset detected

Latest commit: 95b79ec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 15 packages

Name	Type
@ensnode/ensnode-sdk	Patch
ensapi	Patch
ensadmin	Patch
ensindexer	Patch
ensrainbow	Patch
fallback-ensapi	Patch
@ensnode/ensnode-react	Patch
@ensnode/ensrainbow-sdk	Patch
@ensnode/datasources	Patch
@ensnode/ponder-metadata	Patch
@ensnode/ensnode-schema	Patch
@ensnode/ponder-subgraph	Patch
@ensnode/shared-configs	Patch
@docs/ensnode	Patch
@docs/ensrainbow	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
admin.ensnode.io	Ready	Preview, Comment	Dec 30, 2025 2:49pm
ensnode.io	Ready	Preview, Comment	Dec 30, 2025 2:49pm
ensrainbow.io	Ready	Preview, Comment	Dec 30, 2025 2:49pm

[lightwalker-eth]

@stevedylandev This looks like an exciting direction to me. Appreciate your advice on next steps 👍

[lightwalker-eth]

@stevedylandev Reviewed and shared feedback