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
57 lines
2.0 KiB
Markdown
57 lines
2.0 KiB
Markdown
# 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
|
|
1. **AuthController** - Login, logout, token refresh endpoints
|
|
2. **TeamMemberController** - CRUD for team members
|
|
3. **ProjectController** - CRUD, status transitions, estimates
|
|
4. **AllocationController** - CRUD, bulk operations, matrix view
|
|
5. **ActualController** - CRUD, logging hours
|
|
6. **CapacityController** - Capacity calculations, holidays, PTO
|
|
7. **ReportController** - Forecast, utilization, costs, variance reports
|
|
8. **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:generate` runs 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
|