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

Author: mcalthrop

apps/api/recipes_api/openapi_spec.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, TypedDict, cast
+from typing import TypedDict
 
 import yaml
+from pydantic import BaseModel, ConfigDict, ValidationError
 
 
 class OpenApiInfo(TypedDict):
@@ -16,6 +17,24 @@ class OpenApiInfo(TypedDict):
     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():
@@ -26,23 +45,13 @@ def load_openapi_info(path: Path) -> OpenApiInfo:
         raise FileNotFoundError(msg)
 
     parsed = yaml.safe_load(path.read_text(encoding="utf-8"))
-    if not isinstance(parsed, dict):
-        raise ValueError("OpenAPI document root must be a mapping")
-    root = cast(dict[str, Any], parsed)
-    info_raw = root.get("info")
-    if not isinstance(info_raw, dict):
-        raise ValueError("OpenAPI document must contain an info object")
-    info = cast(dict[str, Any], info_raw)
-
-    title = info.get("title")
-    version = info.get("version")
-    description = info.get("description")
-    if not isinstance(title, str) or not isinstance(version, str) or not isinstance(
-        description,
-        str,
-    ):
-        raise ValueError(
-            "OpenAPI info.title, info.version, and info.description must be strings",
-        )
-
-    return OpenApiInfo(title=title, version=version, description=description)
+    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

@@ -6,6 +6,7 @@
 from unittest.mock import MagicMock, patch
 
 import pytest
+from pydantic import ValidationError
 
 from recipes_api.openapi_spec import load_openapi_info
 
@@ -30,6 +31,52 @@ def test_load_openapi_info_returns_info_from_yaml(mock_safe_load: MagicMock, tmp
     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