[High] Publish OpenAPI 3 specification and enforce API contract tests in CI

[robertocarlous]

Labels: priority/high, area/api, documentation, feature

Body:

## Summary
NeuroWealth has a growing REST surface (`/api/auth`, `/api/portfolio`, `/api/deposit`, `/api/vault`, `/api/admin`, etc.) but no machine-readable API contract. This slows frontend development, makes breaking changes likely, and blocks third-party integrations.

## Problem
- No OpenAPI/Swagger spec exists in the repo
- Response shapes vary (`{ error }` vs `{ success, data }` vs nested `transaction`)
- Zod validators exist per-route but are not exported as API documentation
- New contributors must read route files to understand request/response contracts

## User story
**As a** frontend or integrator developer,  
**I want** an accurate OpenAPI document for all public endpoints,  
**so that** I can generate clients, validate payloads, and catch breaking API changes in CI.

## Proposed solution
### Phase 1 — Spec generation
- Add `openapi.yaml` (or `docs/openapi.yaml`) covering:
  - Auth (`/api/auth/challenge`, `/verify`, `/logout`)
  - Portfolio, transactions, deposit, withdraw, vault
  - Health (`/health/live`, `/health/ready`)
  - Public vs authenticated vs admin routes clearly tagged
- Document auth scheme: `Bearer JWT`
- Include standard error schema:
  ```json
  { "error": "string", "details": "optional array/object" }

  ## Acceptance criteria

 OpenAPI 3.1 spec committed and versioned
 All public /api/* routes documented with request/response schemas
 Security schemes documented (Bearer, Admin token, Internal token)
 CI job validates spec syntax and runs contract tests on key endpoints
 README links to API docs and contribution guide for updating spec
 Breaking change policy documented (semver for API surface)

[Senorespecial]

I would like to work on this issue, pls assign

[mich-sys]

I'd like to apply for this. The goal is clear: produce a versioned OpenAPI 3.1 spec covering all public endpoints and wire a CI contract test job to catch breaking changes.
My approach: I'll use zod-to-openapi or swagger-jsdoc to generate the spec from the route files rather than hand-writing it, so the documentation stays in sync with the actual validation logic. I'll cover all six route groups auth, portfolio, transactions, deposit/withdraw, vault, health with correct security tagging (Bearer JWT, Admin token, Internal token) and a unified error schema. The CI job will use swagger-cli validate on PRs to catch spec drift, plus a lightweight contract test against key endpoints.
README and contribution guide updates for the spec update workflow are included in the deliverables.
Available to start immediately and can deliver within the campaign window.

[shadrach68]

I would like to work on this issue because I am a full-stack developer with 5+ years experience. I focus on identifying root causes and delivering clean, efficient, and maintainable solutions, with thorough testing to ensure reliable results.

[TheDEV111]

Hi, I would like to work on this issue. I'll approach this problem by creating a complete OpenAPI 3.1 specification for NeuroWealth’s REST API to improve developer experience and API reliability. I’ll document all public endpoints, request/response schemas, authentication flows, and standard error formats while ensuring the spec stays aligned with existing Zod validators. I’ll also add validation tooling, CI contract checks, and documentation updates to make future API changes safer and easier to maintain.

[Truphile]

Hi there,

I would love to take on this issue! I have thoroughly reviewed the requirements and the problem statement, and I am ready to start working on a clean, production-ready implementation.

If assigned, you can expect:

• A clean architecture implementation that adheres strictly to the project's existing design patterns.
• Proper handling of edge cases, strict validation, and robust error handling.
• Comprehensive unit and integration tests covering all acceptance criteria.

Please assign this issue to me if it is available, and I will get a pull request ready for your review as soon as possible. Thank you!

[Biokes]

Hi maintainer,
I'm a Software Engineer and I'd like to take this issue. I understand the requirements and will follow the existing project structure, keep the implementation clean, and include proper tests where applicable.