Generate the OpenAPI document from a single source of truth

[mikewheeleer]

Drive the OpenAPI document from a maintained spec module

Description

The GET /api/v1/openapi.json handler in src/index.ts returns a hand-written object literal listing paths and one-line summaries. It is already drifting from reality — it omits GET /api/v1/config, PATCH /api/v1/config, and GET /api/v1/health/deep query behavior, and several entries have empty operation objects ({}). A hand-maintained literal inevitably diverges from the real routes. This issue moves the spec into a dedicated module and adds a test that keeps it honest against the mounted routes.

Requirements and context

• Repository scope: StableRoute-Org/Stableroute-backend only.
• Create src/openapi.ts (create file) exporting the spec object with complete paths (including GET/PATCH /api/v1/config) and proper operation summaries and basic response codes.
• Have the GET /api/v1/openapi.json handler return the imported spec unchanged in shape.
• Add a drift-guard test that enumerates the app's registered routes (via the Express router stack) and asserts every non-internal path appears in the spec, so future routes must be documented.
• Keep openapi: "3.0.3" and the existing info block.

Suggested execution

• Fork the repo and create a branch
• git checkout -b enhancement/openapi-31-single-source
• Implement changes
  • Write code in: create src/openapi.ts; update the handler in src/index.ts.
  • Write comprehensive tests in: create src/__tests__/openapi.test.ts — fetch /api/v1/openapi.json, validate top-level fields, and assert no registered route is missing from paths.
  • Add documentation: mention the spec module and drift guard in README.md.
  • Add TSDoc on the exported spec.
  • Validate security: ensure the spec does not leak internal-only routes or secrets.
• Test and commit

Test and commit

• Run npm run build, npm run lint, and npm test.
• Cover edge cases: a route present in code but missing from spec must fail the drift test.
• Paste the full npm test output in the PR.

Example commit message

feat(openapi): move spec to a module and add a route-drift guard

Guidelines

• Minimum 95 percent test coverage for impacted code.
• Clear, reviewer-focused documentation.
• Timeframe: 96 hours.

Community & contribution rewards

• 💬 Join the StableRoute community on Discord for questions, reviews, and faster merges: https://discord.gg/37aCpusvx
• ⭐ This is a GrantFox OSS / Official Campaign task and may be rewarded. When your PR is merged you'll be prompted to rate the project — if this issue and the maintainers helped you ship, we'd be grateful for a 5-star rating. Clear questions in Discord and tidy, well-tested PRs are the fastest path to a merge and a reward.

[Jagadeeshftw]

Hi, I’d love to take on this issue! With my expertise in Rust, Stellar, and smart contract development, I can implement a clean and efficient solution.

🚀 Why Me?

• Proven Blockchain Experience – Hands-on work with Stellar, Solidity, and Rust, building secure and optimized smart contracts.
• Open Source Contributor – Actively contributed to 50+ open-source projects, showcasing adaptability and collaboration.
• Efficient & Reliable – I deliver high-quality, production-ready solutions quickly, ensuring security and scalability.

⏱ Timeline

I estimate completing this within 24 hours. Let me know if I can proceed!

[grantfox-oss]

🦊 GrantFox — @Jagadeeshftw has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.