83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# 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
|