Files

T

Fusion 40a940304b 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

2.3 KiB

Raw Blame History

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

{
  "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

{
  "status": "healthy",
  "response_time_ms": 5.2,
  "connections": {
    "active": 2,
    "idle": 3,
    "max": 20
  }
}

API README

Sections:

Overview
Quick Start
Environment Variables
Development Setup
Running Tests
Architecture Overview
Common Commands
Deployment

Architecture Decision Records

Format:

Title
Status (proposed, accepted, deprecated)
Context
Decision
Consequences
Date

ADRs to create:

Session-based authentication (vs JWT)
SQLAlchemy async with PostgreSQL
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

2.3 KiB Raw Blame History