# Design: API Documentation with Scribe

## Technical Approach

### Scribe Configuration
File: `config/scribe.php`

```php
return [
    'title' => 'Headroom API',
    'description' => 'Resource planning and capacity management API',
    'base_url' => env('APP_URL') . '/api',
    'auth' => [
        'enabled' => true,
        'default' => true,
        'in' => 'bearer',
        'use_value' => 'Bearer {token}',
    ],
    'routes' => [
        [
            'match' => ['api/*'],
            'include' => [],
            'exclude' => [],
        ],
    ],
];
```

### Annotation Patterns

#### Authentication Endpoint Example
```php
/**
 * @group Authentication
 * 
 * Authenticate user and issue JWT tokens.
 * 
 * @bodyParam email string required User's email address. Example: user@example.com
 * @bodyParam password string required User's password. Example: secret123
 * 
 * @response 200 {
 *   "data": {
 *     "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
 *     "refresh_token": "abc123def456...",
 *     "token_type": "bearer",
 *     "expires_in": 3600
 *   }
 * }
 * @response 401 {
 *   "message": "Invalid credentials",
 *   "errors": {
 *     "email": ["These credentials do not match our records."]
 *   }
 * }
 * @response 422 {
 *   "message": "Validation failed",
 *   "errors": {
 *     "email": ["The email field is required."],
 *     "password": ["The password field is required."]
 *   }
 * }
 */
public function login(LoginRequest $request): JsonResponse
```

#### CRUD Endpoint Example
```php
/**
 * @group Team Members
 * @authenticated
 * 
 * List all team members with optional filters.
 * 
 * @queryParam active boolean Filter by active status. Example: true
 * @queryParam role_id int Filter by role ID. Example: 1
 * 
 * @response 200 {
 *   "data": [
 *     {
 *       "id": "550e8400-e29b-41d4-a716-446655440000",
 *       "name": "Alice Johnson",
 *       "role": {"id": 1, "name": "Frontend Dev"},
 *       "hourly_rate": 75.00,
 *       "active": true
 *     }
 *   ],
 *   "meta": {"total": 10}
 * }
 */
public function index(Request $request): JsonResponse
```

### Group Organization
| Group          | Controller            | Endpoints |
|----------------|-----------------------|-----------|
| Authentication | AuthController        | 3         |

Additional groups are intentionally deferred until corresponding controllers are added to this repository.

### Authentication Documentation
Include a dedicated section explaining:
1. How to obtain tokens (login endpoint)
2. How to use tokens (Authorization: Bearer {token})
3. Token refresh flow
4. Token expiration (60 min access, 7 day refresh)

## Implementation Order

1. Configure Scribe (`config/scribe.php`)
2. Annotate AuthController (most critical, used by all)
3. Generate documentation (`php artisan scribe:generate`)
4. Verify SwaggerUI at `/api/documentation`

## File Changes

### New Files
- `config/scribe.php` - Scribe configuration

### Modified Files
- `backend/app/Http/Controllers/Api/AuthController.php`
- `backend/config/cors.php`

## Testing
- Run `php artisan scribe:generate` - must complete without errors
- Verify generated docs at `/api/documentation`
- Test "Try it out" functionality for login endpoint