# API Documentation

## Problem

The API lacks comprehensive documentation:
- No auto-generated OpenAPI/Swagger UI
- Health endpoint is minimal (only checks database)
- Missing endpoint documentation and docstrings
- No API README for developer onboarding
- No Architecture Decision Records (ADRs)

## Solution

Provide comprehensive API documentation:

1. **Auto-generated OpenAPI docs** - FastAPI native `/docs` and `/redoc` endpoints
2. **Enhanced health checks** - `/health` with full system status, `/health/db` for database
3. **Endpoint documentation** - Proper docstrings, Pydantic models, response codes
4. **API README** - Developer onboarding guide
5. **Architecture Decision Records** - Document key architectural choices

## Key Features

### OpenAPI Documentation
- Interactive Swagger UI at `/docs`
- ReDoc at `/redoc`
- All endpoints with schemas and examples
- Authentication documented

### Health Monitoring
- `/health` - Overall system health (database, disk, uptime)
- `/health/db` - Database-specific health check
- JSON responses with status indicators

### Developer Documentation
- `apps/api/README.md` - Setup, env vars, testing
- ADRs in `docs/architecture/decisions/`
- Inline code documentation

## Benefits

- **Developer onboarding** - New devs can understand the API quickly
- **API discoverability** - Interactive docs for testing endpoints
- **Health monitoring** - Operations can monitor system health
- **Knowledge preservation** - ADRs capture why decisions were made

## Success Criteria

- [ ] `/docs` loads Swagger UI with all endpoints
- [ ] `/health` returns comprehensive health data
- [ ] `/health/db` returns database status
- [ ] All endpoints have docstrings
- [ ] API README exists with setup instructions
- [ ] At least one ADR exists