OpenAPI 3 spec and interactive docs (e.g. /api/docs)

[Jayrodri088]

Context

External contributors and frontend teams need a single source of truth for request/response shapes. OpenAPI reduces integration drift and speeds reviews.

Complexity & points

Medium — 150 points

Prerequisites (must be merged or satisfied first)

• Bootstrap Express API: response envelope, errors, health, /api/v1 #5 — Express app and /api/v1 routing pattern.
• Stellar wallet challenge-verify auth and JWT sessions #2 — Auth endpoints exist so they can be documented first; expand the spec as other issues merge.

Unblocks (downstream)

• Frontend and partner integrations; fewer “what does this field mean?” review threads.

Goals

• Add OpenAPI 3.x description (YAML or JSON) checked into the repo, covering at minimum: GET /health, auth routes from Stellar wallet challenge-verify auth and JWT sessions #2, and any routes already merged from other issues at the time of implementation.
• Serve interactive docs at a stable path (e.g. /api/docs) using a maintained package (e.g. swagger-ui-express) or static UI; justify choice in PR.
• Document the standard envelope (success, data, error, meta) as reusable components/schemas.
• npm run build (or a dedicated script) validates the spec file in CI-friendly way if feasible.

Out of scope

• Auto-generation from decorators unless you already use a framework that supports it (keep scope small).

Contributor workflow

• Apply on Drips before opening a PR: Claim this issue through the Drips platform before you open a pull request. Unsolicited PRs from unassigned contributors may be closed without review.
• ETA required: Your application must include an ETA for when you will open the first draft PR.
• Draft PR within 24 hours: If a draft PR is not linked on this issue within 24 hours of assignment, maintainers may unassign you so someone else can take the issue.

Acceptance criteria

• /api/docs loads in a browser against a running dev server.
• Spec includes security scheme for Bearer JWT where applicable.
• README or PR notes how to refresh the spec when new endpoints land.

PR submission requirements

• CI: All GitHub Actions workflow runs for this PR must pass (green) before merge; failing checks block merge.
• PR description must include: Closes #15 (adjust if needed).
• List new dependencies with versions (per repo policy).

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 150 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

Warning

Only applications submitted via the apply link above will be considered. Please do not apply by commenting on the issue or opening a PR directly.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[BarryArinze]

@BarryArinze has applied to work on this issue as part of the Stellar Wave Program's 3rd wave.

Hey there.
I’d love to take this on and give the API a clear, reliable source of truth for both frontend and external contributors. I’ll add a clean OpenAPI 3.x spec covering existing routes (starting with /health and auth), define reusable schemas for the standard response envelope, and make sure everything stays easy to extend as new endpoints land.

I’ll serve interactive docs at /api/docs using a lightweight, well-supported solution like swagger-ui-express, and include a simple validation step to keep the spec CI-friendly. I’ll also document how to keep the spec updated going forward.

ETA: Draft PR within 24 hours of assignment.

My goal is to make integration smoother, reduce back-and-forth in reviews, and keep the API self-explanatory as the project grows.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @BarryArinze to this issue.

[drips-wave]

Congratulations, @BarryArinze! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on March 30, 2026.

🧑‍💻 @BarryArinze: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊