Santhosh Janardhanan
b9cb5170da
- Update decision-log with UI layout decisions (Feb 18, 2026) - Update architecture with frontend layout patterns - Update config.yaml with TDD, documentation, UI standards rules - Create p00-api-documentation change (Scribe annotations) - Create p01-ui-foundation change (types, stores, Lucide) - Create p02-app-layout change (AppLayout, Sidebar, TopBar) - Create p03-dashboard-enhancement change (PageHeader, StatCard) - Create p04-content-patterns change (DataTable, FilterBar) - Create p05-page-migrations change (page migrations) - Fix E2E auth tests (11/11 passing) - Add JWT expiry validation to dashboard guard
2.0 KiB
2.0 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 ALL existing API controllers 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
- TeamMemberController - CRUD for team members
- ProjectController - CRUD, status transitions, estimates
- AllocationController - CRUD, bulk operations, matrix view
- ActualController - CRUD, logging hours
- CapacityController - Capacity calculations, holidays, PTO
- ReportController - Forecast, utilization, costs, variance reports
- MasterDataController - Roles, statuses, types management
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
- All controllers have Scribe annotations
php artisan scribe:generateruns without errors- SwaggerUI accessible at
/api/documentation - All 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