Merge pull request #294 from spoo-me/fix/health-response-model

fix: document the /health response schema in OpenAPI

Author: Zingzy

.github/workflows/tests.yaml

@@ -20,6 +20,31 @@ permissions:
   contents: read
 
 jobs:
+  spec-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Regenerate openapi.json and diff against the committed file
+        run: |
+          make openapi
+          git diff --exit-code openapi.json || {
+            echo "::error::openapi.json is stale — run 'make openapi' and commit the result."
+            exit 1
+          }
+
   test:
     runs-on: ubuntu-latest
     strategy:

Makefile

@@ -27,10 +27,15 @@ docker-up:          ## Start full stack (MongoDB + Redis + app)
 docker-down:        ## Stop full stack
 	docker-compose down
 
+# Pinned env so the artifact is reproducible: the servers block comes from
+# APP_URL, and settings refuse to load without MONGODB_URI. Writing through a
+# temp file keeps a failed export from truncating the committed spec.
 openapi:            ## Export OpenAPI spec to openapi.json
+	MONGODB_URI="mongodb://localhost:27017/" APP_URL="https://spoo.me" \
 	uv run python -c \
 		"from app import create_app; import json; app = create_app(); \
-		print(json.dumps(app.openapi(), indent=2))" > openapi.json
+		print(json.dumps(app.openapi(), indent=2))" > openapi.json.tmp
+	mv openapi.json.tmp openapi.json
 
 docs:               ## Open API docs in browser (requires running server)
 	open http://localhost:8000/docs

openapi.json

@@ -28,7 +28,19 @@
             "description": "Successful Response",
             "content": {
               "application/json": {
-                "schema": {}
+                "schema": {
+                  "$ref": "#/components/schemas/HealthResponse"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Unhealthy \u2014 MongoDB is unreachable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HealthResponse"
+                }
               }
             }
           }
@@ -3762,7 +3774,7 @@
               "anyOf": [
                 {
                   "type": "string",
-                  "maxLength": 50
+                  "maxLength": 1000
                 },
                 {
                   "type": "null"
@@ -5001,7 +5013,7 @@
               "anyOf": [
                 {
                   "type": "string",
-                  "maxLength": 50
+                  "maxLength": 1000
                 },
                 {
                   "type": "null"
@@ -10949,6 +10961,58 @@
         "type": "object",
         "title": "HTTPValidationError"
       },
+      "HealthChecks": {
+        "properties": {
+          "mongodb": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "error",
+              "not_configured"
+            ],
+            "title": "Mongodb"
+          },
+          "redis": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "error",
+              "not_configured"
+            ],
+            "title": "Redis"
+          }
+        },
+        "type": "object",
+        "required": [
+          "mongodb",
+          "redis"
+        ],
+        "title": "HealthChecks",
+        "description": "Individual service check statuses inside HealthResponse."
+      },
+      "HealthResponse": {
+        "properties": {
+          "status": {
+            "type": "string",
+            "title": "Status"
+          },
+          "version": {
+            "type": "string",
+            "title": "Version"
+          },
+          "checks": {
+            "$ref": "#/components/schemas/HealthChecks"
+          }
+        },
+        "type": "object",
+        "required": [
+          "status",
+          "version",
+          "checks"
+        ],
+        "title": "HealthResponse",
+        "description": "Response body for GET /health."
+      },
       "LayoutResponse": {
         "properties": {
           "layout": {
@@ -14195,7 +14259,7 @@
   ],
   "servers": [
     {
-      "url": "http://spoo.local:8000",
+      "url": "https://spoo.me",
       "description": "Production"
     }
   ],

routes/health_routes.py

@@ -9,10 +9,10 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
-from fastapi.responses import JSONResponse
+from fastapi import APIRouter, Request, Response
 
 from middleware.openapi import PUBLIC_SECURITY
+from schemas.dto.responses.common import HealthResponse
 
 router = APIRouter(tags=["System"])
 
@@ -22,8 +22,14 @@
     openapi_extra=PUBLIC_SECURITY,
     operation_id="healthCheck",
     summary="Health Check",
+    responses={
+        503: {
+            "description": "Unhealthy — MongoDB is unreachable",
+            "model": HealthResponse,
+        }
+    },
 )
-async def health_check(request: Request) -> JSONResponse:
+async def health_check(request: Request, response: Response) -> HealthResponse:
     """Check the health of the application and its dependencies.
 
     Pings MongoDB and Redis to determine overall system status:
@@ -63,12 +69,10 @@ async def health_check(request: Request) -> JSONResponse:
 
     settings = getattr(request.app.state, "settings", None)
 
-    status_code = 503 if overall == "unhealthy" else 200
-    return JSONResponse(
-        status_code=status_code,
-        content={
-            "status": overall,
-            "version": settings.app_version if settings else "dev",
-            "checks": checks,
-        },
+    if overall == "unhealthy":
+        response.status_code = 503
+    return HealthResponse(
+        status=overall,
+        version=settings.app_version if settings else "dev",
+        checks=checks,
     )

schemas/dto/responses/common.py

@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Literal
 
 from schemas.dto.base import ResponseBase
 
@@ -25,15 +25,16 @@ class ErrorResponse(ResponseBase):
 class HealthChecks(ResponseBase):
     """Individual service check statuses inside HealthResponse."""
 
-    mongodb: str
-    redis: str
+    mongodb: Literal["ok", "error", "not_configured"]
+    redis: Literal["ok", "error", "not_configured"]
 
 
 class HealthResponse(ResponseBase):
     """Response body for GET /health."""
 
     status: str
-    checks: dict[str, str]
+    version: str
+    checks: HealthChecks
 
 
 class MessageResponse(ResponseBase):

tests/smoke/test_openapi.py

@@ -66,6 +66,15 @@ def test_openapi_has_expected_paths(smoke_client: TestClient) -> None:
         assert path in paths, f"Missing path: {path}"
 
 
+def test_openapi_health_has_response_schema(smoke_client: TestClient) -> None:
+    """GET /health should document its response body, including the 503 case."""
+    data = smoke_client.get("/openapi.json").json()
+    responses = data["paths"]["/health"]["get"]["responses"]
+    for status in ("200", "503"):
+        schema = responses[status]["content"]["application/json"]["schema"]
+        assert schema["$ref"] == "#/components/schemas/HealthResponse"
+
+
 def test_openapi_has_components_schemas(smoke_client: TestClient) -> None:
     """OpenAPI spec should have response schemas defined in components."""
     data = smoke_client.get("/openapi.json").json()

tests/unit/schemas/dto/test_common.py

@@ -31,7 +31,12 @@ def test_without_optional_fields(self):
 
 class TestHealthResponse:
     def test_serialization(self):
-        r = HealthResponse(status="healthy", checks={"mongodb": "ok", "redis": "ok"})
+        r = HealthResponse(
+            status="healthy",
+            version="1.0.0",
+            checks={"mongodb": "ok", "redis": "ok"},
+        )
         d = r.model_dump()
         assert d["status"] == "healthy"
+        assert d["version"] == "1.0.0"
         assert d["checks"]["mongodb"] == "ok"