Use models for REST API responses

src/app/endpoints/info.py

@@ -6,13 +6,21 @@
 
 from fastapi import APIRouter, Request
 
+from version import __version__
+from models.responses import InfoResponse
+
 logger = logging.getLogger(__name__)
 router = APIRouter(tags=["info"])
 
 
-@router.get("/info")
-def info_endpoint_handler(request: Request) -> dict:
-    return {
-        "foo": 1,
-        "bar": 2,
-    }
+get_into_responses: dict[int | str, dict[str, Any]] = {
+    200: {
+        "name": "Service name",
+        "version": "Service version",
+    },
+}
+
+
+@router.get("/info", responses=get_into_responses)
+def info_endpoint_handler(request: Request) -> InfoResponse:
+    return InfoResponse(name="foo", version=__version__)

src/models/config.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+
+class Configuration(BaseModel):
+    """Global service configuration."""
+
+    name: str

src/models/responses.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel
+
+
+class InfoResponse(BaseModel):
+    """Model representing a response to a info request.
+
+    Attributes:
+        name: Service name.
+        version: Service version.
+
+    Example:
+        ```python
+        info_response = InfoResponse(
+            name="Lightspeed Stack",
+            version="1.0.0",
+        )
+        ```
+    """
+
+    name: str
+    version: str
+
+    # provides examples for /docs endpoint
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "name": "Lightspeed Stack",
+                    "version": "1.0.0",
+                }
+            ]
+        }
+    }