headroom/openspec/changes/p00-api-documentation/tasks.md

Tasks: API Documentation with Scribe

Phase 1: Configure Scribe

• 0.1 Install Scribe (if not already installed): composer require knuckleswtf/scribe
• 0.2 Publish Scribe config: php artisan vendor:publish --tag=scribe-config
• 0.3 Configure config/scribe.php with Headroom settings
• 0.4 Add /api/documentation to CORS allowed paths

Phase 2: Annotate Controllers

AuthController

• 0.5 Add @group Authentication to class
• 0.6 Document POST /api/auth/login with @bodyParam, @response
• 0.7 Document POST /api/auth/refresh with @authenticated, @response
• 0.8 Document POST /api/auth/logout with @authenticated, @response
• 0.9 Add authentication section to Scribe config

TeamMemberController

• 0.10 Add @group Team Members to class
• 0.11 Document GET /api/team-members with @queryParam filters
• 0.12 Document POST /api/team-members with @bodyParam
• 0.13 Document GET /api/team-members/{id}
• 0.14 Document PUT /api/team-members/{id}
• 0.15 Document DELETE /api/team-members/{id}

ProjectController

• 0.16 Add @group Projects to class
• 0.17 Document GET /api/projects with @queryParam filters
• 0.18 Document POST /api/projects with @bodyParam
• 0.19 Document GET /api/projects/{id}
• 0.20 Document PUT /api/projects/{id}
• 0.21 Document PUT /api/projects/{id}/status
• 0.22 Document PUT /api/projects/{id}/estimate
• 0.23 Document PUT /api/projects/{id}/forecast

AllocationController

• 0.24 Add @group Allocations to class
• 0.25 Document GET /api/allocations (matrix view)
• 0.26 Document POST /api/allocations
• 0.27 Document PUT /api/allocations/{id}
• 0.28 Document DELETE /api/allocations/{id}
• 0.29 Document POST /api/allocations/bulk

ActualController

• 0.30 Add @group Actuals to class
• 0.31 Document GET /api/actuals
• 0.32 Document POST /api/actuals
• 0.33 Document PUT /api/actuals/{id}
• 0.34 Document validation rules (future month rejection)

CapacityController

• 0.35 Add @group Capacity to class
• 0.36 Document GET /api/capacity
• 0.37 Document GET /api/capacity/team
• 0.38 Document GET /api/capacity/revenue
• 0.39 Document POST /api/holidays
• 0.40 Document POST /api/ptos

ReportController

• 0.41 Add @group Reports to class
• 0.42 Document GET /api/reports/forecast
• 0.43 Document GET /api/reports/utilization
• 0.44 Document GET /api/reports/costs
• 0.45 Document GET /api/reports/variance
• 0.46 Document GET /api/reports/allocation

MasterDataController

• 0.47 Add @group Master Data to class
• 0.48 Document GET /api/roles
• 0.49 Document POST /api/roles
• 0.50 Document PUT /api/roles/{id}
• 0.51 Document DELETE /api/roles/{id}
• 0.52 Document project-statuses endpoints
• 0.53 Document project-types endpoints

Phase 3: Generate & Verify

• 0.54 Run php artisan scribe:generate
• 0.55 Verify no errors in generation
• 0.56 Access /api/documentation in browser
• 0.57 Verify all endpoints appear in documentation
• 0.58 Test "Try it out" for login endpoint
• 0.59 Verify authentication flow is documented

Commits

1. chore(docs): Configure Laravel Scribe for API documentation
2. docs(api): Add Scribe annotations to AuthController
3. docs(api): Add Scribe annotations to TeamMemberController
4. docs(api): Add Scribe annotations to ProjectController
5. docs(api): Add Scribe annotations to AllocationController
6. docs(api): Add Scribe annotations to remaining controllers
7. docs(api): Generate and verify SwaggerUI documentation