Enhance health check endpoint to include database status and detailed responses (#325)

Author: thomas-samoht

app/routers/health.py

@@ -1,8 +1,11 @@
 import logging
-from typing import Any
+from typing import Annotated
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
 
+from app.container import get_database
+from app.db.db import Database
 
 logger = logging.getLogger(__name__)
 router = APIRouter()
@@ -14,10 +17,58 @@ def ok_or_error(value: bool) -> str:
 
 @router.get(
     "/health",
-    summary="Health check",
-    tags=["Service Information"],
+    summary="Health Check",
+    description="health check for all dependent API services and components.",
+    status_code=200,
+    responses={
+        200: {
+            "description": "Health check completed (may contain unhealthy components)",
+            "content": {
+                "application/json": {
+                    "examples": {
+                        "all_healthy": {
+                            "summary": "All services healthy",
+                            "value": {
+                                "status": "ok",
+                                "components": {"database": "ok"},
+                            },
+                        },
+                    }
+                }
+            },
+        },
+        500: {"description": "Unexpected error during health check execution"},
+        503: {
+            "description": "One or more components are unhealthy",
+            "content": {
+                "application/json": {
+                    "examples": {
+                        "some_unhealthy": {
+                            "summary": "Some services unhealthy",
+                            "value": {
+                                "status": "error",
+                                "components": {"database": "error"},
+                            },
+                        },
+                    }
+                }
+            },
+        },
+    },
+    tags=["Health"],
 )
-def health() -> dict[str, Any]:
-    return {
-        "status": "ok",
+def health(
+    db: Annotated[Database, Depends(get_database)],
+) -> JSONResponse:
+    logger.info("Checking application health")
+
+    components = {
+        "database": ok_or_error(db.is_healthy()),
     }
+    healthy = ok_or_error(all(value == "ok" for value in components.values()))
+    content = {"status": healthy, "components": components}
+    if healthy == "ok":
+        return JSONResponse(content=content)
+    unhealthy = [name for name, status in components.items() if status != "ok"]
+    logger.warning("Health check failed for components: %s", ", ".join(unhealthy))
+    return JSONResponse(status_code=503, content=content)

tests/test_health_router.py

@@ -0,0 +1,28 @@
+from pytest import MonkeyPatch
+from fastapi.testclient import TestClient
+
+
+def test_health_check_all_components_healthy(
+    client: TestClient, monkeypatch: MonkeyPatch
+) -> None:
+    monkeypatch.setattr("app.db.db.Database.is_healthy", lambda self: True)
+
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["status"] == "ok"
+    assert body["components"]["database"] == "ok"
+
+
+def test_health_check_database_unhealthy(
+    client: TestClient, monkeypatch: MonkeyPatch
+) -> None:
+    monkeypatch.setattr("app.db.db.Database.is_healthy", lambda self: False)
+
+    response = client.get("/health")
+
+    assert response.status_code == 503
+    body = response.json()
+    assert body["status"] == "error"
+    assert body["components"]["database"] == "error"