Kordant/tasks/web-production/29-api-documentation.md

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