# 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