docs(api): generate auth docs and archive p00 change
This commit is contained in:
@@ -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
|
||||
@@ -0,0 +1,51 @@
|
||||
# Proposal: API Documentation with Scribe
|
||||
|
||||
## Overview
|
||||
Add comprehensive API documentation annotations to all Laravel controllers using Laravel Scribe. This enables auto-generated SwaggerUI documentation accessible at `/api/documentation`.
|
||||
|
||||
## Goals
|
||||
- Annotate existing authentication API endpoints with Scribe annotations
|
||||
- Generate browsable API documentation
|
||||
- Ensure documentation stays in sync with implementation
|
||||
- Enable frontend developers to reference accurate API specs
|
||||
|
||||
## Non-Goals
|
||||
- Creating new API endpoints
|
||||
- Modifying existing API responses
|
||||
- Setting up API versioning
|
||||
|
||||
## Priority
|
||||
**HIGH** - This is a prerequisite for UI changes (p01-p05) to ensure API contracts are documented.
|
||||
|
||||
## Scope
|
||||
|
||||
### Controllers to Document
|
||||
1. **AuthController** - Login, logout, token refresh endpoints
|
||||
|
||||
Other controller groups in the broader roadmap are deferred until those controllers/routes are present in this repository.
|
||||
|
||||
### Annotations Required
|
||||
Each endpoint must have:
|
||||
- `@group` - Logical grouping (e.g., "Authentication", "Team Members")
|
||||
- `@authenticated` - For protected endpoints
|
||||
- `@bodyParam` - Request body parameters
|
||||
- `@response` - Example success response
|
||||
- `@response 401|403|422` - Error responses
|
||||
|
||||
## Success Criteria
|
||||
- [ ] AuthController endpoints have Scribe annotations
|
||||
- [ ] `php artisan scribe:generate` runs without errors
|
||||
- [ ] SwaggerUI accessible at `/api/documentation`
|
||||
- [ ] Authentication endpoints documented with request/response examples
|
||||
- [ ] Authentication section explains JWT flow
|
||||
|
||||
## Estimated Effort
|
||||
2-3 hours
|
||||
|
||||
## Dependencies
|
||||
- Existing Laravel backend with controllers
|
||||
- tymon/jwt-auth for authentication examples
|
||||
|
||||
## References
|
||||
- docs/headroom-decision-log.md → Architecture Decisions → API Documentation
|
||||
- openspec/config.yaml → documentation rules
|
||||
@@ -0,0 +1,17 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Generate Authentication API Documentation
|
||||
The system SHALL generate API documentation for authentication endpoints using Laravel Scribe.
|
||||
|
||||
#### Scenario: Generate docs successfully
|
||||
- **WHEN** `php artisan scribe:generate` is run
|
||||
- **THEN** the command completes without errors
|
||||
- **AND** generated documentation includes `POST /api/auth/login`, `POST /api/auth/refresh`, and `POST /api/auth/logout`
|
||||
|
||||
### Requirement: Serve Documentation UI
|
||||
The system SHALL serve documentation at `/api/documentation`.
|
||||
|
||||
#### Scenario: Access generated docs
|
||||
- **WHEN** a client requests `GET /api/documentation`
|
||||
- **THEN** the application responds with HTTP 200
|
||||
- **AND** the page contains the configured API title and authentication guidance
|
||||
@@ -0,0 +1,32 @@
|
||||
# Tasks: API Documentation with Scribe
|
||||
|
||||
## Phase 1: Configure Scribe
|
||||
|
||||
- [x] 0.1 Install Scribe (if not already installed): `composer require knuckleswtf/scribe`
|
||||
- [x] 0.2 Publish Scribe config: `php artisan vendor:publish --tag=scribe-config`
|
||||
- [x] 0.3 Configure `config/scribe.php` with Headroom settings
|
||||
- [x] 0.4 Add `/api/documentation` to CORS allowed paths
|
||||
|
||||
## Phase 2: Annotate Controllers
|
||||
|
||||
### AuthController
|
||||
- [x] 0.5 Add `@group Authentication` to class
|
||||
- [x] 0.6 Document `POST /api/auth/login` with @bodyParam, @response
|
||||
- [x] 0.7 Document `POST /api/auth/refresh` with @authenticated, @response
|
||||
- [x] 0.8 Document `POST /api/auth/logout` with @authenticated, @response
|
||||
- [x] 0.9 Add authentication section to Scribe config
|
||||
|
||||
## Phase 3: Generate & Verify
|
||||
|
||||
- [x] 0.54 Run `php artisan scribe:generate`
|
||||
- [x] 0.55 Verify no errors in generation
|
||||
- [x] 0.56 Access `/api/documentation` in browser
|
||||
- [x] 0.57 Verify all endpoints appear in documentation
|
||||
- [x] 0.58 Test "Try it out" for login endpoint
|
||||
- [x] 0.59 Verify authentication flow is documented
|
||||
|
||||
## Commits
|
||||
|
||||
1. `chore(docs): Configure Laravel Scribe for API documentation`
|
||||
2. `docs(api): Add Scribe annotations to AuthController`
|
||||
3. `docs(api): Generate and verify SwaggerUI documentation`
|
||||
Reference in New Issue
Block a user