docs: publish versioned OpenAPI specification

[charliechinedu19-netizen]

Publish a versioned OpenAPI spec for the public and authenticated routes

Closes #188

What

Complete rewrite and modernization of the OpenAPI specification, covering all 38 HTTP endpoints across the entire API surface. The spec is now served at runtime via Swagger UI and included as a build artifact.

Changes

docs/openapi.yaml — Full rewrite (OpenAPI 3.1.0):

• Fixed POST /api/v1/auth/challenge (was incorrectly documented as GET)
• Fixed GET /api/v1/portfolio/{userId} (was missing the userId path param)
• Removed non-existent POST /api/v1/portfolio/query
• Added all missing endpoints (23 new paths):
  • agent, whatsapp, protocols, vault/state, vault/balance, vault/build-transaction
  • All portfolio sub-routes (/{userId}/history, /{userId}/earnings)
  • transactions/detail/{txHash}, transactions/{id}/events
  • analytics/apy-history, analytics/user-yield, analytics/protocol-performance
  • stellar/metrics
  • All admin routes: dlq/inspect, dlq/retry, dlq/resolve, dlq/replay, stellar/backfill, keys (CRUD), wallets/rotation-status, stellar/metrics
  • Internal routes: agent/status, metrics
• Updated AdminToken security scheme to note both Authorization: Bearer and legacy X-Admin-Token support
• Added request/response examples to every endpoint
• Added reusable responses for Unauthorized, Forbidden, BadRequest, NotFound, Conflict
• 11 component schemas with proper typing

src/index.ts — Runtime Swagger UI serving:

• Loads docs/openapi.yaml at startup via js-yaml
• Serves Swagger UI at /api/v1/docs and /docs
• Serves raw YAML at /api/v1/openapi.yaml and /openapi.yaml
• Graceful fallback if spec file is missing (logs error, continues without UI)

package.json — Build automation:

• validate:spec — validates spec via @apidevtools/swagger-parser
• build:spec — copies spec to dist/docs/openapi.yaml + runs validation
• prebuild now includes build:spec (spec is always validated and bundled)

README.md — Updated documentation:

• Complete route table with all 14 tag groups
• Swagger UI access URLs
• validate:spec command reference

Breaking changes

None. This is purely additive — all existing routes continue to work identically. The only spec corrections (method fix for /auth/challenge, path fixes for /portfolio) bring the spec in line with existing behavior.

How to verify

1. Start the server: npm run dev
2. Open http://localhost:3000/api/v1/docs in a browser
3. Verify the interactive Swagger UI lists all endpoints
4. Verify the raw spec: curl http://localhost:3000/api/v1/openapi.yaml
5. Validate locally: npm run validate:spec

[drips-wave]

@charliechinedu19-netizen 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