headroom/openspec/changes/archive/2026-02-18-p00-api-documentation/design.md

Design: API Documentation with Scribe

Technical Approach

Scribe Configuration

File: config/scribe.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

/**
 * @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

/**
 * @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