openapi spec / docs poc #1550
openapi spec / docs poc #1550
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughAdds CI job to validate committed openapi.json against production, an npm script and TypeScript generator that fetches/writes the spec, and documentation updates including a hidden preview page and docs config pointing to local and production specs. Changes
Sequence Diagram(s)sequenceDiagram
participant CI as GitHub CI
participant Runner as Job Runner
participant Script as generate-openapi.ts
participant Service as ENSApi Service
participant FS as Docs Directory
CI->>Runner: start "OpenAPI Spec Sync Check" job
Runner->>Script: run `npm run openapi:generate` (arg/env/default URL)
Script->>Service: GET /openapi.json
Service-->>Script: 200 + OpenAPI JSON
Script->>FS: write pretty `docs/openapi.json`
Script-->>Runner: log spec version & path count
Runner->>Service: fetch production /openapi.json (for diff)
Runner->>FS: compare committed `docs/openapi.json` vs generated
alt specs match
Runner-->>CI: job passes
else specs differ
Runner-->>CI: job fails and prints regeneration/commit instructions
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ❌ 3❌ Failed checks (2 warnings, 1 inconclusive)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
| - uses: ./.github/actions/setup_node_environment | ||
|
|
||
| - name: Generate OpenAPI spec from production | ||
| run: pnpm --filter ensapi openapi:generate |
There was a problem hiding this comment.
could fail because no linting is done. need to investigate.
There was a problem hiding this comment.
Pull request overview
This PR adds OpenAPI specification generation and documentation capabilities to the ENSNode project. It introduces a script to fetch and save the OpenAPI spec from a running ENSApi instance, integrates it with Mintlify documentation, and adds CI checks to ensure the spec stays in sync with production.
Changes:
- Added a 5,106-line OpenAPI specification file documenting all ENSApi endpoints
- Created a generation script to fetch and update the spec from a running instance
- Configured Mintlify docs to reference both production and local OpenAPI specs
- Added CI workflow to validate spec synchronization on the main branch
Reviewed changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/docs.ensnode.io/openapi.json | Complete OpenAPI 3.1.0 specification documenting all ENSApi endpoints including resolution, meta, explore, and ENSAwards APIs |
| apps/ensapi/scripts/generate-openapi.ts | TypeScript script to fetch OpenAPI spec from running instance and save to docs directory |
| apps/ensapi/package.json | Added npm script openapi:generate to run the generation script |
| docs/docs.ensnode.io/docs.json | Updated configuration to reference production API spec and added hidden preview section for local spec |
| .github/workflows/test_ci.yml | Added CI job to verify OpenAPI spec stays in sync with production on main branch |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * ENSAPI_URL=http://localhost:3223 pnpm openapi:generate | ||
| * | ||
| * Output: | ||
| * Writes openapi.json to the docs directory for Mintilify |
There was a problem hiding this comment.
The comment mentions "Mintilify" but the context suggests this should be "Mintlify" (the documentation platform). This appears to be a typo in the documentation.
| * Writes openapi.json to the docs directory for Mintilify | |
| * Writes openapi.json to the docs directory for Mintlify |
| const response = await fetch(openapiUrl); | ||
|
|
||
| if (!response.ok) { | ||
| console.error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`); | ||
| process.exit(1); | ||
| } |
There was a problem hiding this comment.
The script lacks error handling for network timeouts or when the URL is unreachable. Consider adding a timeout to the fetch call and providing more helpful error messages for common failure scenarios (e.g., connection refused, timeout, invalid JSON response).
.github/workflows/test_ci.yml
Outdated
| # Only run on main branch - PRs may intentionally have different specs | ||
| if: github.ref == 'refs/heads/main' |
There was a problem hiding this comment.
The CI check only runs on the main branch, which means PRs that update the API won't validate that the OpenAPI spec needs to be regenerated. Consider running this check on all branches but only failing on main, or add a comment to the PR when the spec is out of sync.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Fix all issues with AI agents
In @.github/workflows/test_ci.yml:
- Around line 51-55: The openapi-sync-check job currently only runs when
github.ref == 'refs/heads/main', which lets PRs merge with out-of-sync specs;
update the condition on the openapi-sync-check job (the if: line) to also run
for pull requests (e.g., include github.event_name == 'pull_request' or
github.head_ref checks) and mark it non-blocking for PRs by using
continue-on-error: true (or alternatively remove the if entirely and rely on
branch protection or add contributor documentation). Target the job named
openapi-sync-check and the existing if: github.ref == 'refs/heads/main'
condition when making the change.
In `@apps/ensapi/scripts/generate-openapi.ts`:
- Around line 23-24: ensapiUrl may end with a trailing slash causing openapiUrl
to become "//openapi.json"; normalize ensapiUrl before composing openapiUrl (the
variables to change are ensapiUrl and openapiUrl in generate-openapi.ts) by
trimming any trailing '/' from ensapiUrl (or using a URL-safe join) so
openapiUrl is built as `${normalizedEnsapiUrl}/openapi.json` even when
ENSAPI_URL or process.argv[2] includes a trailing slash; ensure
DEFAULT_ENSAPI_URL remains fallback and normalization runs after selecting the
value.
- Line 12: Update the header comment string that reads "Writes openapi.json to
the docs directory for Mintilify" and correct the product name typo to
"Mintlify" so the comment reads "Writes openapi.json to the docs directory for
Mintlify"; locate this exact comment text in generate-openapi.ts and make the
single-word change.
- Around line 28-33: Add a timeout to the fetch in generate-openapi.ts by
creating an AbortSignal via AbortSignal.timeout(ms) and passing it as the signal
option to the fetch(openapiUrl) call; handle the abort case by catching the
thrown error (check for AbortError or error.name === 'AbortError') and log a
clear timeout message before exiting, and ensure the existing non-ok response
handling remains unchanged.
In `@docs/docs.ensnode.io/docs.json`:
- Around line 29-34: The docs.json "Preview" group references a non-existent
page "ensapi/preview"; fix by either adding a new page file named preview.mdx
under the docs/docs.ensnode.io/ensapi/ folder (so the path matches
"ensapi/preview") or remove the entire Preview group entry (the object with
"group": "Preview", "pages": ["ensapi/preview"], "openapi": "./openapi.json",
"hidden": true) from docs.json; update whichever you choose and ensure the
"pages" array references only existing MDX/MD files.
| const ensapiUrl = process.argv[2] || process.env.ENSAPI_URL || DEFAULT_ENSAPI_URL; | ||
| const openapiUrl = `${ensapiUrl}/openapi.json`; |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Handle potential trailing slash in URL.
If ensapiUrl ends with a /, the constructed URL will have //openapi.json. Consider normalizing:
Proposed fix
const ensapiUrl = process.argv[2] || process.env.ENSAPI_URL || DEFAULT_ENSAPI_URL;
- const openapiUrl = `${ensapiUrl}/openapi.json`;
+ const openapiUrl = `${ensapiUrl.replace(/\/+$/, '')}/openapi.json`;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const ensapiUrl = process.argv[2] || process.env.ENSAPI_URL || DEFAULT_ENSAPI_URL; | |
| const openapiUrl = `${ensapiUrl}/openapi.json`; | |
| const ensapiUrl = process.argv[2] || process.env.ENSAPI_URL || DEFAULT_ENSAPI_URL; | |
| const openapiUrl = `${ensapiUrl.replace(/\/+$/, '')}/openapi.json`; |
🤖 Prompt for AI Agents
In `@apps/ensapi/scripts/generate-openapi.ts` around lines 23 - 24, ensapiUrl may
end with a trailing slash causing openapiUrl to become "//openapi.json";
normalize ensapiUrl before composing openapiUrl (the variables to change are
ensapiUrl and openapiUrl in generate-openapi.ts) by trimming any trailing '/'
from ensapiUrl (or using a URL-safe join) so openapiUrl is built as
`${normalizedEnsapiUrl}/openapi.json` even when ENSAPI_URL or process.argv[2]
includes a trailing slash; ensure DEFAULT_ENSAPI_URL remains fallback and
normalization runs after selecting the value.
| const response = await fetch(openapiUrl); | ||
|
|
||
| if (!response.ok) { | ||
| console.error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`); | ||
| process.exit(1); | ||
| } |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider adding a timeout to the fetch request.
The fetch call has no timeout, which could cause the CI job to hang indefinitely if the production API is unresponsive. Node.js fetch supports AbortSignal.timeout():
Proposed fix
- const response = await fetch(openapiUrl);
+ const response = await fetch(openapiUrl, {
+ signal: AbortSignal.timeout(30_000), // 30 second timeout
+ });📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const response = await fetch(openapiUrl); | |
| if (!response.ok) { | |
| console.error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`); | |
| process.exit(1); | |
| } | |
| const response = await fetch(openapiUrl, { | |
| signal: AbortSignal.timeout(30_000), // 30 second timeout | |
| }); | |
| if (!response.ok) { | |
| console.error(`Failed to fetch OpenAPI spec: ${response.status} ${response.statusText}`); | |
| process.exit(1); | |
| } |
🤖 Prompt for AI Agents
In `@apps/ensapi/scripts/generate-openapi.ts` around lines 28 - 33, Add a timeout
to the fetch in generate-openapi.ts by creating an AbortSignal via
AbortSignal.timeout(ms) and passing it as the signal option to the
fetch(openapiUrl) call; handle the abort case by catching the thrown error
(check for AbortError or error.name === 'AbortError') and log a clear timeout
message before exiting, and ensure the existing non-ok response handling remains
unchanged.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.github/workflows/test_ci.yml:
- Around line 58-70: The CI step runs the openapi:generate npm script which
currently relies on a hardcoded production default; make the behavior explicit
by passing the production URL via the ENSAPI_URL env in the workflow step or by
updating the openapi:generate script to accept an ENSAPI_URL argument and
default it to https://api.alpha.ensnode.io; update the step that invokes
openapi:generate to export ENSAPI_URL or call the script with the URL so the
action is explicit and maintainable.
| - name: Generate OpenAPI spec from production | ||
| run: pnpm --filter ensapi openapi:generate | ||
|
|
||
| - 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 |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
🧩 Analysis chain
🏁 Script executed:
# Find the ensapi package and its configuration
find . -name "package.json" -type f | xargs grep -l "ensapi" | head -5Repository: namehash/ensnode
Length of output: 137
🏁 Script executed:
# Search for openapi:generate script definition
rg "openapi:generate" --type jsonRepository: namehash/ensnode
Length of output: 142
🏁 Script executed:
# Find any openapi generator script files
fd -e ts -e js | xargs grep -l "openapi" | grep -i "generate\|api" | head -10Repository: namehash/ensnode
Length of output: 431
🏁 Script executed:
# Examine the OpenAPI generator script
cat -n apps/ensapi/scripts/generate-openapi.tsRepository: namehash/ensnode
Length of output: 1894
🏁 Script executed:
# Check if there's environment variable usage in the script
rg "ENSAPI_URL|process.env" apps/ensapi/scripts/generate-openapi.ts -A 2 -B 2Repository: namehash/ensnode
Length of output: 617
The OpenAPI generator already defaults to production; explicit URL is optional.
The openapi:generate script uses a hardcoded default of https://api.alpha.ensnode.io (the production API), making the CI behavior deterministic. While explicitly passing ENSAPI_URL would improve clarity and maintainability, the current implementation correctly targets production and won't drift due to changing defaults.
🤖 Prompt for AI Agents
In @.github/workflows/test_ci.yml around lines 58 - 70, The CI step runs the
openapi:generate npm script which currently relies on a hardcoded production
default; make the behavior explicit by passing the production URL via the
ENSAPI_URL env in the workflow step or by updating the openapi:generate script
to accept an ENSAPI_URL argument and default it to https://api.alpha.ensnode.io;
update the step that invokes openapi:generate to export ENSAPI_URL or call the
script with the URL so the action is explicit and maintainable.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| "openapi": "./openapi.json", | ||
| "hidden": true | ||
| } | ||
| ] |
There was a problem hiding this comment.
The "hidden" property may not be a valid field in the Mintlify docs.json schema. According to Mintlify documentation, there is no "hidden" property for navigation groups. If you want to hide this section, you should verify this property is supported or use a different approach.
| "openapi": "./openapi.json", | |
| "hidden": true | |
| } | |
| ] | |
| "openapi": "./openapi.json" | |
| } | |
| ] | |
| ] |
Lite PR
Summary
Why
Testing
Notes for Reviewer (Optional)
Pre-Review Checklist (Blocking)
PR Creation Tips
Summary by CodeRabbit
Documentation
Infrastructure
✏️ Tip: You can customize this high-level summary in your review settings.