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,116 @@
+# API Documentation - Design
+
+## Architecture
+
+```
+API Documentation
+├── OpenAPI (FastAPI native)
+│   ├── /docs (Swagger UI)
+│   ├── /redoc (ReDoc)
+│   └── /openapi.json
+├── Health Endpoints
+│   ├── GET /health
+│   └── GET /health/db
+├── API README
+│   └── apps/api/README.md
+└── Architecture Decision Records
+    └── docs/architecture/decisions/
+```
+
+## Component Design
+
+### OpenAPI Documentation
+
+FastAPI automatically generates OpenAPI schema from:
+- Pydantic models (request/response)
+- Endpoint docstrings
+- Path operation parameters
+- Response status codes
+
+**Enhancements needed:**
+- Add descriptions to all Pydantic models
+- Add docstrings to all endpoints
+- Add response examples where helpful
+- Add authentication requirements
+
+### Health Endpoints
+
+**GET /health**
+```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**
+```json
+{
+  "status": "healthy",
+  "response_time_ms": 5.2,
+  "connections": {
+    "active": 2,
+    "idle": 3,
+    "max": 20
+  }
+}
+```
+
+### API README
+
+**Sections:**
+1. Overview
+2. Quick Start
+3. Environment Variables
+4. Development Setup
+5. Running Tests
+6. Architecture Overview
+7. Common Commands
+8. Deployment
+
+### Architecture Decision Records
+
+**Format:**
+- Title
+- Status (proposed, accepted, deprecated)
+- Context
+- Decision
+- Consequences
+- Date
+
+**ADRs to create:**
+1. Session-based authentication (vs JWT)
+2. SQLAlchemy async with PostgreSQL
+3. Docker-based tool instances
+
+## Technical Details
+
+**Libraries:**
+- FastAPI (built-in OpenAPI)
+- Pydantic v2 (schemas)
+- psutil (disk/health metrics)
+
+**Files to modify:**
+- `apps/api/src/main.py` - Add health endpoints
+- All `apps/api/src/api/*.py` - Add docstrings
+- All `apps/api/src/models/*.py` - Add model descriptions
+- `apps/api/src/schemas/*.py` - Add response schemas
+
+## Error Handling
+
+- Health endpoints return 200 even if degraded
+- Failed checks included in response with "degraded" status
+- Never expose sensitive info in health responses