feat: add documentation to some endpoints

backend/kernelCI_app/typeModels/databases.py

@@ -28,6 +28,7 @@
 type Checkout__GitCommitTags = Optional[List[str]]
 type Checkout__GitRepositoryBranch = Optional[str]
 type Checkout__GitRepositoryUrl = Optional[str]
+type Checkout__PatchsetHash = Optional[str]
 
 type Build__Id = str
 type Build__Architecture = Optional[str]

backend/kernelCI_app/typeModels/treeCommits.py

@@ -1,24 +1,15 @@
 from datetime import datetime
 from typing import List
-from pydantic import BaseModel, RootModel, Field
+from pydantic import BaseModel, RootModel
 
 from kernelCI_app.typeModels.commonDetails import BuildStatusCount
+from kernelCI_app.typeModels.treeListing import TestStatusCount
 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
@@ -33,8 +24,8 @@ class TreeCommitsData(BaseModel):
     git_commit_name: Checkout__GitCommitName
     earliest_start_time: datetime
     builds: BuildStatusCount
-    boots: TreeCommitsTestStatusCount
-    tests: TreeCommitsTestStatusCount
+    boots: TestStatusCount
+    tests: TestStatusCount
 
 
 class TreeCommitsResponse(RootModel):

backend/kernelCI_app/typeModels/treeDetails.py

@@ -4,15 +4,27 @@
     BuildHistoryItem,
     DetailsFilters,
     Summary,
+    CommonDetailsBootsResponse,
+    CommonDetailsTestsResponse,
 )
+from kernelCI_app.typeModels.treeListing import BaseCheckouts
 from pydantic import BaseModel
+from kernelCI_app.constants.general import DEFAULT_ORIGIN
 
 
 class TreeLatestPathParameters(BaseModel):
     tree_name: str
     branch: str
 
 
+class TreeLatestQueryParameters(BaseModel):
+    origin: str = DEFAULT_ORIGIN
+
+
+class TreeLatestResponse(BaseCheckouts):
+    api_url: str
+
+
 class TreeCommon(BaseModel):
     hardware: Optional[List[str]]
     tree_url: Optional[str]
@@ -30,6 +42,15 @@ class TreeDetailsBuildsResponse(BaseModel):
 
 
 class TreeQueryParameters(BaseModel):
-    origin: str = "maestro"
+    origin: str
     git_url: str
     git_branch: str
+
+
+class TreeDetailsFullResponse(
+    TreeDetailsBuildsResponse,
+    CommonDetailsBootsResponse,
+    CommonDetailsTestsResponse,
+    SummaryResponse
+):
+    pass

backend/kernelCI_app/typeModels/treeListing.py

@@ -0,0 +1,63 @@
+from typing import List
+from kernelCI_app.typeModels.commonDetails import BuildStatusCount
+from kernelCI_app.typeModels.databases import (
+    Checkout__GitCommitHash,
+    Checkout__GitCommitName,
+    Checkout__GitCommitTags,
+    Checkout__TreeName,
+    Checkout__Id,
+    Checkout__PatchsetHash,
+    Checkout__GitRepositoryBranch,
+    Checkout__GitRepositoryUrl,
+    Timestamp
+)
+from pydantic import BaseModel, Field, RootModel
+
+
+class TestStatusCount(BaseModel):
+    pass_count: int = Field(alias='pass')
+    error_count: int = Field(alias='error')
+    fail_count: int = Field(alias='fail')
+    skip_count: int = Field(alias='skip')
+    miss_count: int = Field(alias='miss')
+    done_count: int = Field(alias='done')
+    null_count: int = Field(alias='null')
+
+
+class BaseCheckouts(BaseModel):
+    git_repository_url: Checkout__GitRepositoryUrl
+    git_commit_hash: Checkout__GitCommitHash
+    git_commit_name: Checkout__GitCommitName
+
+
+class CommonCheckouts(BaseCheckouts):
+    git_repository_branch: Checkout__GitRepositoryBranch
+    start_time: Timestamp
+
+
+class Checkout(CommonCheckouts):
+    build_status: BuildStatusCount
+    test_status: TestStatusCount
+    boot_status: TestStatusCount
+    tree_names: List[Checkout__TreeName]
+    git_commit_tags: List[Checkout__GitCommitTags]
+
+
+class CheckoutFast(CommonCheckouts):
+    id: Checkout__Id
+    tree_name: Checkout__TreeName
+    patchset_hash: Checkout__PatchsetHash
+    git_commit_tags: Checkout__GitCommitTags
+
+
+class TreeListingResponse(RootModel):
+    root: List[Checkout]
+
+
+class TreeListingFastResponse(RootModel):
+    root: List[CheckoutFast]
+
+
+class TreeListingQueryParameters(BaseModel):
+    origin: str
+    intervalInDays: int

backend/kernelCI_app/views/treeDetailsView.py

@@ -1,11 +1,13 @@
 from typing import List
-from django.http import JsonResponse
 from http import HTTPStatus
-from django.views import View
-from kernelCI_app.helpers.errorHandling import create_error_response
+from rest_framework.views import APIView
+from rest_framework.response import Response
 from kernelCI_app.helpers.filters import (
     FilterParams,
 )
+from drf_spectacular.utils import extend_schema
+from pydantic import ValidationError
+from kernelCI_app.helpers.errorHandling import create_api_error_response
 from kernelCI_app.helpers.treeDetails import (
     call_based_on_compatible_and_misc_platform,
     decide_if_is_boot_filtered_out,
@@ -33,9 +35,13 @@
 from kernelCI_app.viewCommon import create_details_build_summary
 
 from kernelCI_app.typeModels.issues import Issue, IssueDict
+from kernelCI_app.typeModels.treeDetails import (
+    TreeDetailsFullResponse,
+    TreeQueryParameters
+)
 
 
-class TreeDetails(View):
+class TreeDetails(APIView):
     def __init__(self):
         self.processedTests = set()
         self.filters = None
@@ -159,24 +165,29 @@ def _sanitize_rows(self, rows):
         self.build_summary = create_details_build_summary(self.builds)
         self.build_issues = convert_issues_dict_to_list(self.processed_build_issues)
 
+    @extend_schema(
+        responses=TreeDetailsFullResponse,
+        parameters=[TreeQueryParameters],
+        methods=["GET"]
+    )
     def get(self, request, commit_hash: str | None):
         rows = get_tree_details_data(request, commit_hash)
 
         self.filters = FilterParams(request)
 
         if len(rows) == 0:
-            return create_error_response(
+            return create_api_error_response(
                 error_message="Tree not found", status_code=HTTPStatus.OK
             )
 
         self._sanitize_rows(rows)
 
-        return JsonResponse(
-            {
-                "builds": self.builds,
-                "boots": self.bootHistory,
-                "tests": self.testHistory,
-                "summary": {
+        try:
+            valid_response = TreeDetailsFullResponse(
+                builds=self.builds,
+                boots=self.bootHistory,
+                tests=self.testHistory,
+                summary={
                     "builds": {
                         "status": self.build_summary["builds"],
                         "architectures": self.build_summary["architectures"],
@@ -207,12 +218,12 @@ def get(self, request, commit_hash: str | None):
                         "failed_platforms": list(self.testPlatformsWithErrors),
                     },
                 },
-                "common": {
+                common={
                     "hardware": list(self.hardwareUsed),
                     "tree_url": self.tree_url,
                     "git_commit_tags": self.git_commit_tags,
                 },
-                "filters": {
+                filters={
                     "all": {
                         "configs": list(self.global_configs),
                         "architectures": list(self.global_architectures),
@@ -227,7 +238,11 @@ def get(self, request, commit_hash: str | None):
                     "tests": {
                         "issues": list(self.unfiltered_test_issues),
                     },
-                },
-            },
-            safe=False,
-        )
+                }
+            )
+        except ValidationError as e:
+            return create_api_error_response(
+                error_message=e.json(), status_code=HTTPStatus.INTERNAL_SERVER_ERROR
+            )
+
+        return Response(valid_response.model_dump())