feat: automate OpenAPI spec sync with endpoint filtering#132
Conversation
Add sync-openapi.ts script that fetches upstream openapi.json from
js-recall main branch and filters it for public documentation.
Blocked path patterns:
- /api/admin/** (admin endpoints)
- /api/user/** (user dashboard endpoints)
- /api/auth/login (user login)
- /api/competitions/{id}/partners (partners listing)
- /nfl/** (NFL endpoints)
Blocked tags: Admin, User, NFL
Also injects missing security scheme definitions (AgentApiKey, bearerAuth)
until upstream fixes are merged.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR introduces automation for synchronizing the OpenAPI specification from the upstream js-recall repository, filtering out private/internal endpoints before generating public documentation.
- Adds a new sync script that fetches, filters, and injects missing security scheme definitions into the OpenAPI spec
- Updates the OpenAPI spec with new metadata (title, contact, license) and security schemes
- Updates documentation descriptions to be more concise across multiple endpoint files
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/sync-openapi.ts |
New script that fetches upstream OpenAPI spec, filters blocked endpoints/tags, and injects missing security scheme definitions |
specs/competitions.json |
Updated OpenAPI spec with new metadata, security schemes (AgentApiKey, bearerAuth, PrivyCookie), simplified tag descriptions, and endpoint reordering |
docs/reference/endpoints/trade.mdx |
Simplified description from detailed explanation to concise "Trading endpoints" |
docs/reference/endpoints/price.mdx |
Simplified description from detailed explanation to concise "Price information endpoints" |
docs/reference/endpoints/health.mdx |
Simplified description from detailed explanation to concise "Health check endpoints" |
docs/reference/endpoints/competition.mdx |
Simplified description and reordered endpoint operations to match new spec structure |
docs/reference/endpoints/auth.mdx |
Simplified description from detailed explanation to concise "Authentication endpoints" |
docs/reference/endpoints/agent.mdx |
Simplified description from detailed explanation to concise "Agent management endpoints" |
docs/reference/endpoints/account.mdx |
New empty documentation file for Account tag (has no associated endpoints) |
docs/reference/endpoints/leaderboard.mdx |
Deleted file (endpoints likely filtered or tag removed) |
docs/reference/endpoints/arenas.mdx |
Deleted file (endpoints likely filtered or tag removed) |
docs/reference/endpoints/agents.mdx |
Deleted file (endpoints likely filtered or tag removed) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.
|
@dtbuchholz I'll re-run now that these upstream openapi fixes to bearerAuth capitalization and AgentApiKey missing schema are in. |
|
ah i missed your comment about this PR. we'll first have to deploy these changes to prod, though. |
|
my script checks main (a scary inconsistency with our deployment strategy, which checks for tagged releases), so I'm actually good to re-run now 🤪 |
|
ah, shoot. my PR didn't run |
Upstream js-recall PR #1610 merged, adding AgentApiKey definition and fixing bearerAuth typo. Injections no longer needed.
|
Draft while we fix upstream issue related to Agents, Arenas, Leaderboards, Perpetual Futures, NFL not having tag metadata. |
carsonfarmer
left a comment
carsonfarmer
left a comment
There was a problem hiding this comment.
Couple of nits for you @derrekcoleman.
| /^\/nfl\//, | ||
| ]; | ||
|
|
||
| const BLOCKED_TAGS = ["Admin", "User", "NFL"]; |
There was a problem hiding this comment.
This is another spot where it doesn't feel right to have something like NFL hard coded here. I think, if this is just a temp solution, this is fine for now... but we should try to have a more sustainable means of filtering here if not.
There was a problem hiding this comment.
Completely agree. Dan and I were chatting; something more thoughtful upstream in js-recall is best, potentially related to tags in OpenAPI.
i.e. API endpoint authors should be responsible for indicating whether their endpoints are (something like) public or private
Remove BLOCKED_PATH_PATTERNS in favor of filtering operations by tag.
This simplifies the logic and makes /api/auth/login and
/api/competitions/{id}/partners visible (they have allowed tags).
- Replace manual fetch/validation with @apidevtools/swagger-parser - Use bundle() to handle resolution and consolidation - Add proper OpenAPIV3 types from openapi-types - Improve filterPathItem to use typed HTTP methods and preserve path metadata
Adds
scripts/sync-openapi.tsthat fetches upstreamopenapi.jsonfrom js-recall main and filters it for public docs.Filtering approach
Uses tag-based filtering to exclude internal endpoints. Operations tagged with blocked tags are removed, and paths that become empty after filtering are excluded entirely.
Blocked tags
Admin- admin endpointsUser- user dashboard endpointsNFL- NFL prediction game endpointsImplementation details
@apidevtools/swagger-parserfor robust OpenAPI spec parsing and validationOPENAPI_SOURCE_URLenvironment variableBuild pipeline
build:openapinow runs sync → generate → prettier in sequence.