feat(api): add issues view documentation

Part of #86
Closes #814
Closes #816

backend/kernelCI_app/typeModels/issuesView.py

@@ -0,0 +1,7 @@
+from typing import List
+from pydantic import RootModel
+from kernelCI_app.typeModels.issues import Issue
+
+
+class IssuesResponse(RootModel):
+    root: List[Issue]

backend/kernelCI_app/views/issuesView.py

@@ -1,18 +1,21 @@
 from typing import Dict, List, Optional
-from django.http import JsonResponse
 from django.db import connection
-from django.views import View
+from rest_framework.views import APIView
+from rest_framework.response import Response
+from drf_spectacular.utils import extend_schema
+from pydantic import ValidationError
 
-from kernelCI_app.helpers.errorHandling import create_error_response
+from kernelCI_app.helpers.errorHandling import create_api_error_response
 from kernelCI_app.utils import (
     convert_issues_dict_to_list,
     create_issue,
 )
 from http import HTTPStatus
 from kernelCI_app.typeModels.issues import Issue, IssueDict
+from kernelCI_app.typeModels.issuesView import IssuesResponse
 
 
-class IssueView(View):
+class IssueView(APIView):
     fields = ["incident_id", "id", "version", "comment", "report_url"]
 
     def get_dict_record(self, row) -> Dict[str, str]:
@@ -78,29 +81,44 @@ def get_build_issues(self, build_id: str) -> List[Issue]:
             rows = cursor.fetchall()
         return self.sanitize_rows(rows)
 
+    @extend_schema(
+        responses=IssuesResponse
+    )
     def get(
         self, _request, test_id: Optional[str] = None, build_id: Optional[str] = None
-    ) -> JsonResponse:
+    ) -> Response:
         if test_id:
             test_issues = self.get_test_issues(test_id)
 
             if len(test_issues) == 0:
-                return create_error_response(
+                return create_api_error_response(
                     error_message="No issues were found for this test",
                     status_code=HTTPStatus.OK,
                 )
 
-            return JsonResponse(test_issues, safe=False)
+            try:
+                valid_test_response = IssuesResponse(test_issues)
+            except ValidationError as e:
+                return Response(data=e.json(), status=HTTPStatus.INTERNAL_SERVER_ERROR)
+
+            return Response(valid_test_response.model_dump())
+
         if build_id:
             build_issues = self.get_build_issues(build_id)
 
             if len(build_issues) == 0:
-                return create_error_response(
+                return create_api_error_response(
                     error_message="No issues were found for this build",
                     status_code=HTTPStatus.OK,
                 )
 
-            return JsonResponse(build_issues, safe=False)
-        return create_error_response(
+            try:
+                valid_build_response = IssuesResponse(build_issues)
+            except ValidationError as e:
+                return Response(data=e.json(), status=HTTPStatus.INTERNAL_SERVER_ERROR)
+
+            return Response(valid_build_response.model_dump())
+
+        return create_api_error_response(
             error_message="A test or build ID must be provided"
         )

backend/schema.yml

@@ -26,6 +26,28 @@ paths:
               schema:
                 $ref: '#/components/schemas/BuildDetailsResponse'
           description: ''
+  /api/build/{build_id}/issues:
+    get:
+      operationId: build_issues_retrieve
+      parameters:
+      - in: path
+        name: build_id
+        schema:
+          type: string
+        required: true
+      tags:
+      - build
+      security:
+      - cookieAuth: []
+      - basicAuth: []
+      - {}
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IssuesResponse'
+          description: ''
   /api/build/{build_id}/tests:
     get:
       operationId: build_tests_retrieve
@@ -475,6 +497,28 @@ paths:
               schema:
                 $ref: '#/components/schemas/TestDetailsResponse'
           description: ''
+  /api/test/{test_id}/issues:
+    get:
+      operationId: test_issues_retrieve
+      parameters:
+      - in: path
+        name: test_id
+        schema:
+          type: string
+        required: true
+      tags:
+      - test
+      security:
+      - cookieAuth: []
+      - basicAuth: []
+      - {}
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IssuesResponse'
+          description: ''
   /api/tree/:
     get:
       operationId: tree_list
@@ -1686,6 +1730,11 @@ components:
       - type: 'null'
     Issue__Version:
       type: integer
+    IssuesResponse:
+      items:
+        $ref: '#/components/schemas/Issue'
+      title: IssuesResponse
+      type: array
     LocalFilters:
       properties:
         issues: