feat(api): OpenAPI info from spec (PLAN 3.3) (#8)

* feat(api): load OpenAPI info from packages/openapi spec (PLAN 3.3)

Wire FastAPI title, version, and description from openapi.yaml via
load_openapi_info(); add PyYAML and tests. Mark PLAN 3.3 complete.

Made-with: Cursor

* refactor(api): extract openapi path helper and lean on mocks in tests

Move resolve_openapi_spec_path to openapi_paths.py; require Path in
load_openapi_info; use unittest.mock in openapi_spec and main tests;
add openapi_paths_test.

Made-with: Cursor

* feat(api): validate OpenAPI info with Pydantic

Replace manual dict checks with small Pydantic models; wrap
ValidationError as ValueError. Extend openapi_spec tests for extra
keys, invalid payloads, and exception chaining.

Made-with: Cursor

* docs(api): clarify monorepo .parent chain in openapi_paths

Made-with: Cursor

Author: mcalthrop

PLAN.md

@@ -17,7 +17,7 @@ Tasks and subtasks for building the bread-recipes app (SolidJS + Python REST + O
 
 - [x] **3.1** Create the Python project layout, dependency files, and a minimal ASGI app (e.g. FastAPI) wired for local dev.
 - [x] **3.2** Implement a data-access abstraction and a static implementation (files under repo) so swapping to DB/CMS later does not reshape route handlers.
-- [ ] **3.3** Wire FastAPI/OpenAPI **`info`** (title, version, description) from **`packages/openapi/openapi.yaml`** so the running app matches the committed spec and those values are not duplicated in code (e.g. `main.py`).
+- [x] **3.3** Wire FastAPI/OpenAPI **`info`** (title, version, description) from **`packages/openapi/openapi.yaml`** so the running app matches the committed spec and those values are not duplicated in code (e.g. `main.py`).
 - [ ] **3.4** Implement REST handlers to match the OpenAPI spec (response shapes and status codes); keep behaviour aligned with the spec.
 - [ ] **3.5** Tests with 100% coverage and a coverage gate in CI for the API package; add `README.md` for install, run, and test commands.
 

apps/api/pyproject.toml

@@ -10,6 +10,7 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
   "fastapi==0.115.12",
+  "pyyaml==6.0.2",
   "uvicorn[standard]==0.34.3",
 ]
 

apps/api/recipes_api/main.py

@@ -4,17 +4,22 @@
 
 from fastapi import FastAPI
 
+from recipes_api.openapi_paths import resolve_openapi_spec_path
+from recipes_api.openapi_spec import load_openapi_info
+
 
 class HealthPayload(TypedDict):
     """Response body for the health check."""
 
     status: str
 
 
+_openapi_info = load_openapi_info(resolve_openapi_spec_path())
+
 app = FastAPI(
-    title="Bread Recipes API",
-    version="0.1.0",
-    description="REST API for browsing bread recipes (list overview and full detail).",
+    title=_openapi_info["title"],
+    version=_openapi_info["version"],
+    description=_openapi_info["description"],
 )
 
 

apps/api/recipes_api/main_test.py

@@ -1,13 +1,29 @@
 """Smoke tests for the minimal ASGI app (``main``)."""
 
-from fastapi.testclient import TestClient
+import importlib
+from unittest.mock import patch
 
-from recipes_api.main import app
+from fastapi.testclient import TestClient
 
-client = TestClient(app)
+import recipes_api.main as main_module
 
 
 def test_health_returns_ok_status() -> None:
+    client = TestClient(main_module.app)
     response = client.get("/health")
     assert response.status_code == 200
     assert response.json() == {"status": "ok"}
+
+
+def test_app_metadata_comes_from_load_openapi_info() -> None:
+    fake = {
+        "title": "Mock API",
+        "version": "2.0.0",
+        "description": "Loaded via mock",
+    }
+    with patch("recipes_api.openapi_spec.load_openapi_info", return_value=fake):
+        importlib.reload(main_module)
+        assert main_module.app.title == fake["title"]
+        assert main_module.app.version == fake["version"]
+        assert main_module.app.description == fake["description"]
+    importlib.reload(main_module)

apps/api/recipes_api/openapi_paths.py

@@ -0,0 +1,10 @@
+"""Monorepo paths for OpenAPI artefacts."""
+
+from pathlib import Path
+
+
+def resolve_openapi_spec_path() -> Path:
+    """Resolve the path to ``packages/openapi/openapi.yaml`` in the monorepo checkout."""
+    # .parent chain from this file: recipes_api/ → apps/api/ → apps/ → monorepo root (four times).
+    root = Path(__file__).resolve().parent.parent.parent.parent
+    return root / "packages" / "openapi" / "openapi.yaml"

apps/api/recipes_api/openapi_paths_test.py

@@ -0,0 +1,16 @@
+"""Tests for ``openapi_paths``."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+from recipes_api import openapi_paths
+
+
+def test_resolve_openapi_spec_path() -> None:
+    with patch.object(
+        openapi_paths,
+        "__file__",
+        "/workspace/apps/api/recipes_api/openapi_paths.py",
+    ):
+        resolved = openapi_paths.resolve_openapi_spec_path()
+    assert resolved == Path("/workspace/packages/openapi/openapi.yaml")

apps/api/recipes_api/openapi_spec.py

@@ -0,0 +1,57 @@
+"""Load OpenAPI document metadata from a YAML spec file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+
+class OpenApiInfo(TypedDict):
+    """Subset of OpenAPI ``info`` used to configure FastAPI."""
+
+    title: str
+    version: str
+    description: str
+
+
+class _OpenApiInfoBlock(BaseModel):
+    """``info`` object: only the fields we need; other OpenAPI keys are ignored."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    title: str
+    version: str
+    description: str
+
+
+class _OpenApiRootForInfo(BaseModel):
+    """Minimal root shape: must include ``info``; other top-level keys are ignored."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    info: _OpenApiInfoBlock
+
+
+def load_openapi_info(path: Path) -> OpenApiInfo:
+    """Read ``info.title``, ``info.version``, and ``info.description`` from the YAML spec."""
+    if not path.is_file():
+        msg = (
+            f"OpenAPI spec not found at {path}. "
+            "Run the API from the monorepo checkout so packages/openapi is available."
+        )
+        raise FileNotFoundError(msg)
+
+    parsed = yaml.safe_load(path.read_text(encoding="utf-8"))
+    try:
+        root = _OpenApiRootForInfo.model_validate(parsed)
+    except ValidationError as exc:
+        raise ValueError("OpenAPI document is invalid or missing required info fields") from exc
+
+    return OpenApiInfo(
+        title=root.info.title,
+        version=root.info.version,
+        description=root.info.description,
+    )

apps/api/recipes_api/openapi_spec_test.py

@@ -0,0 +1,84 @@
+"""Tests for ``openapi_spec`` (load ``info`` from YAML)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from pydantic import ValidationError
+
+from recipes_api.openapi_spec import load_openapi_info
+
+
+@patch("recipes_api.openapi_spec.yaml.safe_load")
+def test_load_openapi_info_returns_info_from_yaml(mock_safe_load: MagicMock, tmp_path: Path) -> None:
+    mock_safe_load.return_value = {
+        "info": {
+            "title": "Bread Recipes API",
+            "version": "0.1.0",
+            "description": "REST API for browsing bread recipes (list overview and full detail).",
+        }
+    }
+    path = tmp_path / "spec.yaml"
+    path.write_text("ignored: true\n", encoding="utf-8")
+    info = load_openapi_info(path)
+    assert info == {
+        "title": "Bread Recipes API",
+        "version": "0.1.0",
+        "description": "REST API for browsing bread recipes (list overview and full detail).",
+    }
+    mock_safe_load.assert_called_once()
+
+
+@patch("recipes_api.openapi_spec.yaml.safe_load")
+def test_load_openapi_info_ignores_extra_openapi_keys(mock_safe_load: MagicMock, tmp_path: Path) -> None:
+    mock_safe_load.return_value = {
+        "openapi": "3.1.0",
+        "info": {
+            "title": "T",
+            "version": "1.0.0",
+            "description": "D",
+            "license": {"name": "MIT"},
+        },
+        "paths": {},
+    }
+    path = tmp_path / "spec.yaml"
+    path.write_text("x", encoding="utf-8")
+    assert load_openapi_info(path) == {
+        "title": "T",
+        "version": "1.0.0",
+        "description": "D",
+    }
+
+
+@patch("recipes_api.openapi_spec.yaml.safe_load")
+@pytest.mark.parametrize(
+    "parsed",
+    [
+        None,
+        [],
+        {},
+        {"openapi": "3.1.0"},
+        {"info": {"title": "only title"}},
+        {"info": {"title": "t", "version": "v", "description": 123}},
+    ],
+)
+def test_load_openapi_info_invalid_document_raises_value_error(
+    mock_safe_load: MagicMock,
+    tmp_path: Path,
+    parsed: object,
+) -> None:
+    mock_safe_load.return_value = parsed
+    path = tmp_path / "spec.yaml"
+    path.write_text("x", encoding="utf-8")
+    with pytest.raises(ValueError, match="invalid or missing required info") as exc_info:
+        load_openapi_info(path)
+    assert isinstance(exc_info.value.__cause__, ValidationError)
+
+
+def test_load_openapi_info_missing_file_raises() -> None:
+    path = MagicMock(spec=Path)
+    path.is_file.return_value = False
+    with pytest.raises(FileNotFoundError, match="OpenAPI spec not found"):
+        load_openapi_info(path)