Improve Pydantic model documentation for OpenAPI schema

backend/app/models.py

@@ -23,11 +23,30 @@ class FindingStatusUpdate(BaseModel):
 
 
 class Finding(BaseModel):
-    id: str
-    category: str
-    severity: str
-    title: str
-    description: str = ""
+    id: str = Field(
+    ...,
+    description="Unique identifier of the finding",
+    examples=["F-001"]
+)
+    category: str = Field(
+    ...,
+    description="Category of the finding",
+    examples=["SQL Injection"]
+)
+    severity: str = Field(
+    ...,
+    description="Severity level of the finding",
+    examples=["High"]
+)
+    title: str = Field(
+    ...,
+    description="Short title of the finding",
+    examples=["SQL Injection Vulnerability"]
+)
+    description: str = Field(
+         default="",
+         description="Detailed description of the finding"
+     )
     location: Optional[Location] = None
     metadata: Dict[str, Any] = Field(default_factory=dict)
     reachability: Optional[Reachability] = None
@@ -36,11 +55,29 @@ class Finding(BaseModel):
 
 
 class ScanResponse(BaseModel):
-    job_id: str
-    project_name: str
-    repo_path: str
-    findings: List[Finding]
-    scanners: Dict[str, Any]
+    job_id: str = Field(
+        ...,
+        description="Unique scan job identifier",
+        examples=["job-123"]
+    )
+    project_name: str = Field(
+        ...,
+        description="Name of the scanned project",
+        examples=["PatchPilot"]
+    )
+    repo_path: str = Field(
+        ...,
+        description="Path to the scanned repository",
+        examples=["C:/Users/ADMIN/PatchPilot"]
+    )
+    findings: List[Finding] = Field(
+        ...,
+        description="List of findings generated by the scan"
+    )
+    scanners: Dict[str, Any] = Field(
+        ...,
+        description="Results produced by different scanners"
+    )
 
 
 class Fix(BaseModel):