feat(api): add tree commits documentation

Part of #86
Closes #811

Author: murilx

backend/kernelCI_app/typeModels/treeCommits.py

@@ -0,0 +1,41 @@
+from datetime import datetime
+from typing import List
+from pydantic import BaseModel, RootModel, Field
+
+from kernelCI_app.typeModels.commonDetails import BuildStatusCount
+from kernelCI_app.typeModels.databases import (
+    Checkout__GitCommitHash,
+    Checkout__GitCommitName
+)
+
+
+class TreeCommitsTestStatusCount(BaseModel):
+    fail_count: int = Field(alias="fail")
+    error_count: int = Field(alias="error")
+    miss_count: int = Field(alias="miss")
+    pass_count: int = Field(alias="pass")
+    done_count: int = Field(alias="done")
+    skip_count: int = Field(alias="skip")
+    null_count: int = Field(alias="null")
+
+
+class TreeCommitsQueryParameters(BaseModel):
+    origin: str
+    git_url: str
+    git_branch: str
+    start_time_stamp_in_seconds: str
+    end_time_stamp_in_seconds: str
+    # TODO: Add filters field in this model
+
+
+class TreeCommitsData(BaseModel):
+    git_commit_hash: Checkout__GitCommitHash
+    git_commit_name: Checkout__GitCommitName
+    earliest_start_time: datetime
+    builds: BuildStatusCount
+    boots: TreeCommitsTestStatusCount
+    tests: TreeCommitsTestStatusCount
+
+
+class TreeCommitsResponse(RootModel):
+    root: List[TreeCommitsData]

backend/kernelCI_app/views/treeCommitsHistory.py

@@ -1,8 +1,7 @@
 from datetime import datetime, timezone
-from django.http import JsonResponse, HttpResponseBadRequest
 from django.db import connection
 from http import HTTPStatus
-from kernelCI_app.helpers.errorHandling import create_error_response
+from kernelCI_app.helpers.errorHandling import create_api_error_response
 from kernelCI_app.helpers.filters import (
     UNKNOWN_STRING,
     FilterParams,
@@ -16,12 +15,17 @@
     env_misc_value_or_default,
 )
 from kernelCI_app.typeModels.databases import FAIL_STATUS
-from kernelCI_app.utils import getErrorResponseBody, is_boot
+from kernelCI_app.utils import is_boot
 from rest_framework.views import APIView
 from rest_framework.response import Response
-from rest_framework import status
+from drf_spectacular.utils import extend_schema
 from typing import Dict, List, Optional
 from kernelCI_app.helpers.treeDetails import create_checkouts_where_clauses
+from kernelCI_app.typeModels.treeCommits import (
+    TreeCommitsQueryParameters,
+    TreeCommitsResponse,
+)
+from pydantic import ValidationError
 
 
 # TODO Move this endpoint to a function so it doesn't
@@ -355,7 +359,12 @@ def _process_time_range(self, request) -> None:
         except Exception as ex:
             log_message(ex)
 
-    def get(self, request, commit_hash):
+    @extend_schema(
+        responses=TreeCommitsResponse,
+        parameters=[TreeCommitsQueryParameters],
+        methods=["GET"],
+    )
+    def get(self, request, commit_hash: Optional[str]) -> Response:
         origin_param = request.GET.get("origin")
         git_url_param = request.GET.get("git_url")
         git_branch_param = request.GET.get("git_branch")
@@ -367,9 +376,8 @@ def get(self, request, commit_hash):
             missing_params.append("origin")
 
         if missing_params:
-            return Response(
-                {"error": f"Missing parameters: {', '.join(missing_params)}"},
-                status=status.HTTP_400_BAD_REQUEST,
+            return create_api_error_response(
+                error_message=f"Missing parameters: {', '.join(missing_params)}",
             )
 
         if None not in (start_timestamp, end_timestamp):
@@ -379,7 +387,7 @@ def get(self, request, commit_hash):
             self.filterParams = FilterParams(request)
             self.setup_filters()
         except InvalidComparisonOP as e:
-            return HttpResponseBadRequest(getErrorResponseBody(str(e)))
+            return create_api_error_response(error_message=str(e))
 
         self.field_values = {
             "commit_hash": commit_hash,
@@ -478,7 +486,7 @@ def get(self, request, commit_hash):
             rows = cursor.fetchall()
 
         if not rows:
-            return create_error_response(
+            return create_api_error_response(
                 error_message="History of tree commits not found",
                 status_code=HTTPStatus.OK,
             )
@@ -519,4 +527,9 @@ def get(self, request, commit_hash):
                 }
             )
 
-        return JsonResponse(results, safe=False)
+        try:
+            valid_response = TreeCommitsResponse(results)
+        except ValidationError as e:
+            return Response(data=e.json(), status=HTTPStatus.INTERNAL_SERVER_ERROR)
+
+        return Response(valid_response.model_dump(by_alias=True))

backend/schema.yml

@@ -582,6 +582,36 @@ paths:
         schema:
           type: string
         required: true
+      - in: query
+        name: end_time_stamp_in_seconds
+        schema:
+          title: End Time Stamp In Seconds
+          type: string
+        required: true
+      - in: query
+        name: git_branch
+        schema:
+          title: Git Branch
+          type: string
+        required: true
+      - in: query
+        name: git_url
+        schema:
+          title: Git Url
+          type: string
+        required: true
+      - in: query
+        name: origin
+        schema:
+          title: Origin
+          type: string
+        required: true
+      - in: query
+        name: start_time_stamp_in_seconds
+        schema:
+          title: Start Time Stamp In Seconds
+          type: string
+        required: true
       tags:
       - tree
       security:
@@ -590,7 +620,11 @@ paths:
       - {}
       responses:
         '200':
-          description: No response body
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TreeCommitsResponse'
+          description: ''
   /api/tree/{commit_hash}/summary:
     get:
       operationId: tree_summary_retrieve
@@ -2092,6 +2126,69 @@ components:
       - is_selected
       title: Tree
       type: object
+    TreeCommitsData:
+      properties:
+        git_commit_hash:
+          $ref: '#/components/schemas/Checkout__GitCommitHash'
+        git_commit_name:
+          $ref: '#/components/schemas/Checkout__GitCommitName'
+        earliest_start_time:
+          format: date-time
+          title: Earliest Start Time
+          type: string
+        builds:
+          $ref: '#/components/schemas/BuildStatusCount'
+        boots:
+          $ref: '#/components/schemas/TreeCommitsTestStatusCount'
+        tests:
+          $ref: '#/components/schemas/TreeCommitsTestStatusCount'
+      required:
+      - git_commit_hash
+      - git_commit_name
+      - earliest_start_time
+      - builds
+      - boots
+      - tests
+      title: TreeCommitsData
+      type: object
+    TreeCommitsResponse:
+      items:
+        $ref: '#/components/schemas/TreeCommitsData'
+      title: TreeCommitsResponse
+      type: array
+    TreeCommitsTestStatusCount:
+      properties:
+        fail:
+          title: Fail
+          type: integer
+        error:
+          title: Error
+          type: integer
+        miss:
+          title: Miss
+          type: integer
+        pass:
+          title: Pass
+          type: integer
+        done:
+          title: Done
+          type: integer
+        skip:
+          title: Skip
+          type: integer
+        'null':
+          title: 'Null'
+          type: integer
+      required:
+      - fail
+      - error
+      - miss
+      - pass
+      - done
+      - skip
+      - 'null'
+      title: TreeCommitsTestStatusCount
+      type: object
     TreeCommon:
       properties:
         hardware: