Fusion
40a940304b
- Create enhanced health endpoints with /health and /health/db - Add comprehensive docstrings to all API endpoints - Add Pydantic response models with Field descriptions - Create apps/api/README.md with setup guide - Create ADR-001 for session auth decision - Create ADR-002 for async SQLAlchemy decision - Quality gates: Python syntax OK, TypeScript OK
126 lines
2.2 KiB
Markdown
126 lines
2.2 KiB
Markdown
# API Documentation Specification
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
1. **OpenAPI Documentation**: Auto-generated at `/docs` and `/redoc`
|
|
2. **Health Endpoints**: `/health` and `/health/db` with comprehensive status
|
|
3. **Endpoint Documentation**: All endpoints have docstrings and Pydantic models
|
|
4. **API README**: `apps/api/README.md` with developer onboarding
|
|
5. **Architecture Decision Records**: Document key architectural choices
|
|
|
|
### Non-Functional Requirements
|
|
|
|
1. **Performance**: Health checks complete in < 100ms
|
|
2. **Security**: Health endpoints don't expose sensitive data
|
|
3. **Maintainability**: Documentation stays in sync with code
|
|
|
|
## API Specification
|
|
|
|
### GET /health
|
|
|
|
Returns overall system health status.
|
|
|
|
**Response 200:**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"timestamp": "2026-05-19T12:00:00Z",
|
|
"version": "0.1.0",
|
|
"checks": {
|
|
"database": {
|
|
"status": "healthy",
|
|
"response_time_ms": 5.2
|
|
},
|
|
"disk": {
|
|
"status": "healthy",
|
|
"free_gb": 45.2,
|
|
"total_gb": 100.0
|
|
}
|
|
},
|
|
"uptime_seconds": 3600
|
|
}
|
|
```
|
|
|
|
### GET /health/db
|
|
|
|
Returns database-specific health status.
|
|
|
|
**Response 200:**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"response_time_ms": 5.2
|
|
}
|
|
```
|
|
|
|
### GET /docs
|
|
|
|
FastAPI Swagger UI (auto-generated).
|
|
|
|
### GET /redoc
|
|
|
|
FastAPI ReDoc (auto-generated).
|
|
|
|
## Documentation Requirements
|
|
|
|
### Endpoint Docstrings
|
|
|
|
Every endpoint must have:
|
|
- Description of what it does
|
|
- Request/response model descriptions
|
|
- Authentication requirements
|
|
- Error responses
|
|
|
|
### Pydantic Models
|
|
|
|
Every model must have:
|
|
- `description` field metadata
|
|
- Example values where helpful
|
|
- Proper typing
|
|
|
|
### API README Structure
|
|
|
|
```markdown
|
|
# Headquarter API
|
|
|
|
## Overview
|
|
## Quick Start
|
|
## Environment Variables
|
|
## Development
|
|
## Testing
|
|
## Architecture
|
|
## Deployment
|
|
```
|
|
|
|
## ADR Template
|
|
|
|
```markdown
|
|
# ADR-XXX: Title
|
|
|
|
## Status
|
|
Accepted
|
|
|
|
## Context
|
|
What is the issue we're facing?
|
|
|
|
## Decision
|
|
What did we decide?
|
|
|
|
## Consequences
|
|
What are the trade-offs?
|
|
|
|
## Date
|
|
2026-05-19
|
|
```
|
|
|
|
## Quality Gates
|
|
|
|
- `/docs` loads successfully
|
|
- `/health` returns 200 with valid JSON
|
|
- `/health/db` returns database status
|
|
- All endpoints have docstrings
|
|
- API README is complete
|
|
- At least one ADR exists
|