docs: comprehensive API documentation

- 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
2026-05-19 21:31:20 +02:00
parent e344e961d6
commit 40a940304b
25 changed files with 1848 additions and 88 deletions
@@ -0,0 +1,125 @@
+# 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