52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# 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
|