feat: comprehensive api documentation with OpenAPI/Swagger spec

[ai-mountain]

Summary

The project previously documented its API only as a small table in the README — no machine-readable contract, no request/response schemas, no error codes, and no way to interactively explore or test the endpoints.

This PR adds a complete OpenAPI 3.0.3 specification generated from the existing shared TypeScript contracts, serves it through interactive Swagger UI at /api-docs, and exposes the raw spec at /api-docs/openapi.json for Postman / Insomnia import and client codegen. It also corrects one error-contract bug so the documented behavior is truthful: invalid leaderboard query parameters now return a clean 400 instead of leaking a raw validation dump as a 500.
Highlights:

• docs/openapi.yaml — all 6 endpoints, 18 component schemas, 5 query parameters, real examples, and documented 400 / 500 error responses.
• Swagger UI mounted with a relaxed CSP without weakening the security headers on the rest of the API.
• README updated with links, a services-table entry, and a Postman/codegen example.

Related Issue

Closes: #32

Change Type (select all that apply)

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Documentation update
• Breaking change (fix or feature that would change existing behavior)
• Other: error-contract correction (500 → 400 on invalid query params)

Real Behavior Proof

Built and ran the compiled server (node backend/dist/src/server.js):
Swagger UI is live

$ curl -s -o /dev/null -w "HTTP %{http_code} | %{content_type}\n" localhost:4000/api-docs/
HTTP 200 | text/html; charset=utf-8
# <title>TAO Passport API Docs</title>

Machine-readable spec serves and parses

$ curl -s localhost:4000/api-docs/openapi.json | python3 -c "import sys,json;d=json.load(sys.stdin);print('openapi:',d['openapi']);print('paths:',list(d['paths']));print('schemas:',len(d['components']['schemas']))"
openapi: 3.0.3
paths: ['/health', '/api/passport/sample', '/api/passport/{walletAddress}', '/api/achievements', '/api/reputation/signals', '/api/reputation/leaderboard']
schemas: 18

Invalid leaderboard query now returns 400 (was 500)

$ curl -s -w "\nHTTP %{http_code}\n" "localhost:4000/api/reputation/leaderboard?limit=999"
{"error":"Invalid leaderboard query parameters: limit: Too big: expected number to be <=50"}
HTTP 400

Invalid wallet address still returns 400

$ curl -s -w "\nHTTP %{http_code}\n" localhost:4000/api/passport/bad
{"error":"Invalid Substrate wallet address format."}
HTTP 400

API keeps strict security headers (helmet CSP unaffected by the docs route)

$ curl -s -D - -o /dev/null localhost:4000/health | grep -i content-security-policy
Content-Security-Policy: default-src 'self';base-uri 'self';...;script-src 'self';...

All internal spec references resolve

total $refs: 30 | broken: 0
ALL REFS RESOLVE ✓

Validation

Check	Command	Result
Type check	npm run typecheck	✅ clean (all workspaces)
Lint	npm run lint --workspace backend	✅ clean
Build	npm run build	✅ backend + frontend built
Tests	npm test	✅ 14/14 pass
Server boot	node backend/dist/src/server.js	✅ boots, endpoints respond

Checklist

• Spec covers all existing endpoints with request/response schemas
• Error responses (400, 500) documented
• Query parameters documented (category, cursor, limit, page, sort)
• Examples added for each endpoint
• Interactive Swagger UI served at /api-docs
• Raw OpenAPI JSON exposed for Postman / codegen import
• README updated with links to the API docs
• Security headers on the API verified unaffected
• typecheck, lint, build, and test all pass
• No breaking changes to existing endpoints