1.8 KiB
1.8 KiB
Proposal: API Documentation with Scribe
Overview
Add comprehensive API documentation annotations to all Laravel controllers using Laravel Scribe. This enables auto-generated SwaggerUI documentation accessible at /api/documentation.
Goals
- Annotate existing authentication API endpoints with Scribe annotations
- Generate browsable API documentation
- Ensure documentation stays in sync with implementation
- Enable frontend developers to reference accurate API specs
Non-Goals
- Creating new API endpoints
- Modifying existing API responses
- Setting up API versioning
Priority
HIGH - This is a prerequisite for UI changes (p01-p05) to ensure API contracts are documented.
Scope
Controllers to Document
- AuthController - Login, logout, token refresh endpoints
Other controller groups in the broader roadmap are deferred until those controllers/routes are present in this repository.
Annotations Required
Each endpoint must have:
@group- Logical grouping (e.g., "Authentication", "Team Members")@authenticated- For protected endpoints@bodyParam- Request body parameters@response- Example success response@response 401|403|422- Error responses
Success Criteria
- AuthController endpoints have Scribe annotations
php artisan scribe:generateruns without errors- SwaggerUI accessible at
/api/documentation - Authentication endpoints documented with request/response examples
- Authentication section explains JWT flow
Estimated Effort
2-3 hours
Dependencies
- Existing Laravel backend with controllers
- tymon/jwt-auth for authentication examples
References
- docs/headroom-decision-log.md → Architecture Decisions → API Documentation
- openspec/config.yaml → documentation rules