127 lines
3.2 KiB
Markdown
127 lines
3.2 KiB
Markdown
# 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
|