headroom/openspec/changes/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	5
Team Members	TeamMemberController	5
Projects	ProjectController	8
Allocations	AllocationController	6
Actuals	ActualController	5
Capacity	CapacityController	6
Reports	ReportController	5
Master Data	MasterDataController	9

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. Annotate TeamMemberController
4. Annotate ProjectController
5. Annotate AllocationController
6. Annotate ActualController
7. Annotate CapacityController
8. Annotate ReportController
9. Annotate MasterDataController
10. Generate documentation (php artisan scribe:generate)
11. Verify SwaggerUI at /api/documentation

File Changes

New Files

• config/scribe.php - Scribe configuration

Modified Files

• backend/app/Http/Controllers/Api/AuthController.php
• backend/app/Http/Controllers/Api/TeamMemberController.php
• backend/app/Http/Controllers/Api/ProjectController.php
• backend/app/Http/Controllers/Api/AllocationController.php
• backend/app/Http/Controllers/Api/ActualController.php
• backend/app/Http/Controllers/Api/CapacityController.php
• backend/app/Http/Controllers/Api/ReportController.php
• backend/app/Http/Controllers/Api/MasterDataController.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