# 29. API Documentation (OpenAPI/tRPC Docs)

meta:
  id: web-production-29
  feature: web-production
  priority: P2
  depends_on: []
  tags: [api, documentation, production]

objective:
- Generate and publish comprehensive API documentation for internal and external developers

deliverables:
- Auto-generated API documentation
- Interactive API explorer
- Authentication documentation
- Error code reference

steps:
1. Set up tRPC documentation generation:
   - Use trpc-openapi or @trpc/openapi-v3 to generate OpenAPI spec
   - Or use trpc-docs or @trpc/doc-generator
   - Export spec as JSON/YAML
2. Create documentation site:
   - Use Swagger UI or Scalar for interactive docs
   - Host at /api/docs or separate docs subdomain
   - Include request/response examples
   - Include authentication requirements
3. Document all routers:
   - User router: login, signup, profile, family
   - Billing router: subscription, checkout, webhooks
   - DarkWatch router: watchlist, exposures, scan
   - VoicePrint router: enrollments, analysis
   - SpamShield router: rules, phone check
   - HomeTitle router: properties, monitoring
   - RemoveBrokers router: listings, removals
   - Alerts router: list, resolve, correlation
   - Admin router: user management, blog
4. Add authentication docs:
   - Session cookie authentication
   - JWT bearer token authentication
   - API key authentication (for extensions)
   - Clerk webhook handling
5. Add error documentation:
   - Standard error codes (400, 401, 403, 404, 429, 500)
   - tRPC error codes and meanings
   - Rate limit headers explanation
6. Add webhook documentation:
   - Stripe webhook events
   - Clerk webhook events
   - Payload schemas and verification
7. Keep docs in sync:
   - Auto-generate on build
   - CI check for doc changes
   - Version docs with API versions

tests:
- Unit: Test OpenAPI spec generation
- Integration: Verify docs site loads and examples work
- Review: Team review for accuracy

acceptance_criteria:
- API docs accessible at /api/docs
- All tRPC routers documented with input/output schemas
- Interactive explorer allowing test requests
- Authentication methods documented with examples
- All error codes explained with examples
- Webhook payloads documented with verification steps
- Docs auto-generated from code (single source of truth)
- Examples use realistic test data

validation:
- Navigate to /api/docs → interactive explorer loads
- Try user.me endpoint → returns example response
- Check auth section → all methods documented
- Review webhook docs → verification steps clear

notes:
- trpc-openapi requires adding meta tags to procedures
- Consider using Scalar (modern alternative to Swagger UI)
- Docs should be public but sensitive endpoints marked as auth-required
- Keep examples updated when schemas change