docs: accurate OpenAPI spec and API.md for all v1 routes

[teethaking]

Closes #65 Closes #71

docs: accurate OpenAPI spec and API.md for all v1 routes

Summary

Makes the OpenAPI spec and checked-in API reference faithful to the running code. Every implemented route now has a corresponding operation with a unique operationId, correct security declarations, accurate request/response schemas, and no fictional fields or stale paths.

Changes

src/config/swagger.ts

• Fixed servers[].url from /api → /api/v1 so Swagger Try-it-out sends requests to the right base path
• Added all 9 resource tags with descriptions (Health, Auth, Users, Modules, Credentials, Rewards, Referrals, Notifications, Sync, Employer)
• Extended apis scan to include src/app.ts (health route) and src/routes/**/*.ts
• Expanded top-level description with auth scheme, rate-limit header format, and error envelope

src/docs/schemas.ts

• Added all previously missing component schemas: ErrorResponse, PublicUser, UpdateUserInput, ChangePasswordInput, UpdateWalletInput, ReferralCodeResponse, ApplyReferralInput, ApplyReferralResponse, ReferralStats, RegisterDeviceInput, NotificationPreferencesInput, NotificationLog, SyncProgressEvent, SyncCompletionEvent, SyncResult, SyncResponse, CandidateSummary, EmployerSearchResponse, CandidateProfile, ContactCandidateInput, ContactCandidateResponse
• Fixed enum values to match runtime (learner/employer not LEARNER/EMPLOYER)
• Corrected CredentialList.meta field names (hasNextPage/hasPrevPage to match actual response)

All controllers

• Added operationId to all 28 operations
• Added security: [] override on all public routes (auth endpoints, GET /modules, GET /modules/:id, GET /credentials/verify/:onChainId, GET /users/:id) so they don't inherit the global bearer requirement
• Fixed stale paths in user.controller.ts: PUT /users/profile → PATCH /users/me, added missing GET /users/:id, PATCH /users/password, PATCH /users/wallet operations
• Added full JSDoc to employer.controller.ts — all three functions were completely undocumented
• Added $ref: '#/components/schemas/ErrorResponse' to all error response statuses
• Added description fields with behavioural detail (rate-limit notes, plan gating, idempotency behaviour, score threshold, etc.)

docs/API.md

• Full rewrite reflecting actual controller behaviour
• Base URL corrected to /api/v1 throughout (old doc used /v1/ directly and mismatched the mount path)
• Removed fictional/stale fields: language, asset: "USDC", timeSpent, anonymousId, matchScore, availableForHire
• Preview/stub routes (PATCH /users/password, PATCH /users/wallet) clearly marked with warnings
• Added rate-limit table, plan-tier table, error code reference, and per-endpoint behaviour notes

Testing

• TypeScript diagnostics: no errors on all 13 changed files
• Swagger UI (/api-docs) will resolve all $ref schema references without broken links
• No runtime code was modified — all changes are JSDoc comments and the swagger config

Acceptance criteria checklist

• Every non-health route maps to one OpenAPI operation
• All operationIds are unique (28 total)
• Schemas match runtime response shapes
• No fictional or stale endpoint presented as implemented
• Public routes carry security: []; protected routes carry bearerAuth
• docs/API.md matches the spec