docs(api): generate auth docs and archive p00 change

2026-02-18 14:26:51 -05:00
parent 032da7c40c
commit cdfb15bbfd
21 changed files with 3214 additions and 147 deletions
--- a/openspec/changes/archive/2026-02-18-p00-api-documentation/design.md
+++ b/openspec/changes/archive/2026-02-18-p00-api-documentation/design.md
@@ -0,0 +1,126 @@
+# 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