Keep the published OpenAPI specification in sync with the implemented routes

[priscaenoch]

Problem

The indexer serves /api/openapi.yaml and the repository depends on swagger-jsdoc/swagger-ui-express, but nothing verifies that the published specification matches the routes that actually exist. Given the very large API surface and the presence of stub/unmounted routers elsewhere in the repository, the spec can silently drift from reality, which misleads the frontend and any external integrator.

What needs to be done

• Determine whether the spec is generated from annotations or maintained by hand.
• Add a CI check that fails when the implemented routes and the published spec disagree (for example by generating the spec and diffing it against the committed artifact, or by reusing the existing route-validation tooling).
• Ensure endpoints that are experimental or return mock data are marked as such in the spec (coordinate with the mock-data issue).
• Document how to regenerate the spec.

Files

• indexer/src/api.js (spec route)
• .github/workflows/ci.yml
• docs/

Acceptance deliverables

• The published OpenAPI spec provably matches the implemented routes.
• Drift fails CI.

Tests to pass

• The spec-drift check passes on the current main and fails when a route is added without a spec update.

[samuel2926i39-art]

i will complete the task as fast as possible, i will do the maximum workflow and create the PR. kindly assign

[grantfox-oss]

🦊 GrantFox — @samuel2926i39-art has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #23)
2. Your PR will be reviewed by the octraban maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@samuel2926i39-art's PR #36 was approved and merged by @priscaenoch.

🏆 @samuel2926i39-art: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (48 total points). Track your full progress on GrantFox.

👏 Great work, @samuel2926i39-art! Keep contributing to octraban.