# 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
1. **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:generate` runs 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
