Add OpenAPI docs and sync check

[Favourof]

OpenAPI / API Reference for Frontend and Integrators

Summary

• closes OpenAPI / API reference for frontend and integrators #118 — Add OpenAPI 3 reference for /api/* routes
• add optional Swagger UI in non-production
• add CI sync check so the spec stays aligned with the route table
• document the new API reference entry points for frontend and integrator use

Changes

closes #118 — OpenAPI 3 spec for /api/* routes

Problem: The backend had route documentation in Markdown, but no machine-readable OpenAPI contract for frontend consumers, integrators, or tooling.

Fix:

• Added a full OpenAPI 3.0.3 spec in src/openapi/spec.ts
• Documented all /api/* routes, including:
  • auth
  • portfolio
  • transactions
  • deposit / withdraw
  • vault
  • analytics
  • protocols
  • stellar metrics
  • admin routes
  • WhatsApp webhook endpoints
• Defined reusable schemas for:
  • auth challenge / verify
  • portfolio and transaction responses
  • protocol rate and agent status payloads
  • vault and analytics responses
  • validation and error envelopes
• Added bearer auth and admin token security schemes where appropriate

---

closes #118 — Optional Swagger UI behind auth in non-prod

Problem: The API needed a browsable reference for humans, but it should not be exposed publicly in production.

Fix:

• Added src/routes/docs.ts
• Exposed:
  • GET /docs
  • GET /openapi.json
• In non-production:
  • /docs serves a Swagger UI page
  • /openapi.json returns the OpenAPI document
• The JSON spec endpoint is protected by bearer auth
• In production, both endpoints return 404

---

closes #118 — CI check to keep the spec in sync

Problem: The OpenAPI spec could drift from the actual route table over time.

Fix:

• Added scripts/check-openapi.ts
• Added npm run openapi:check
• Hooked the check into .github/workflows/node-ci.yml
• The check compares discovered route handlers in src/routes/* against the documented OpenAPI paths and fails CI if they diverge

---

Supporting updates

Added:

• docs/API_REFERENCE.md updates pointing to the new OpenAPI docs entry points
• src/index.ts now mounts the docs router

[drips-wave]

@Favourof Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits