From 8816fd79170b3f851d4b6bbcbdadb0dabdaf45ae Mon Sep 17 00:00:00 2001
From: David Graham <dpgraham4401@gmail.com>
Date: Tue, 10 Oct 2023 15:51:29 -0400
Subject: [PATCH] update our schema documentation for various views

---
 server/apps/sites/views/site_views.py   | 20 ++++++++++++++++----
 server/apps/trak/urls.py                |  2 +-
 server/apps/trak/views/manifest_view.py | 21 +++++++++++++++------
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/server/apps/sites/views/site_views.py b/server/apps/sites/views/site_views.py
index f43e507dd..1450e08fd 100644
--- a/server/apps/sites/views/site_views.py
+++ b/server/apps/sites/views/site_views.py
@@ -1,5 +1,6 @@
 import logging
 
+from django.db.models import QuerySet
 from django.utils.decorators import method_decorator
 from django.views.decorators.cache import cache_page
 from drf_spectacular.utils import extend_schema, inline_serializer
@@ -62,6 +63,17 @@ class RcraSiteView(RetrieveAPIView):
     permission_classes = [permissions.IsAuthenticated]
 
 
+@extend_schema(
+    responses=RcraSiteSerializer(many=True),
+    request=inline_serializer(
+        "handler_search",
+        fields={
+            "epaId": serializers.CharField(),
+            "siteName": serializers.CharField(),
+            "siteType": serializers.CharField(),
+        },
+    ),
+)
 class SiteSearchView(ListAPIView):
     """
     Search for locally saved hazardous waste sites ("Generators", "Transporters", "Tsdf's")
@@ -70,11 +82,11 @@ class SiteSearchView(ListAPIView):
     queryset = RcraSite.objects.all()
     serializer_class = RcraSiteSerializer
 
-    def get_queryset(self):
+    def get_queryset(self: ListAPIView) -> QuerySet[RcraSite]:
         queryset = RcraSite.objects.all()
-        epa_id_param = self.request.query_params.get("epaId")
-        name_param = self.request.query_params.get("siteName")
-        site_type_param: str = self.request.query_params.get("siteType")
+        epa_id_param: str | None = self.request.query_params.get("epaId")
+        name_param: str | None = self.request.query_params.get("siteName")
+        site_type_param: str | None = self.request.query_params.get("siteType")
         if epa_id_param is not None:
             queryset = queryset.filter(epa_id__icontains=epa_id_param)
         if name_param is not None:
diff --git a/server/apps/trak/urls.py b/server/apps/trak/urls.py
index 0817a9305..e8368996e 100644
--- a/server/apps/trak/urls.py
+++ b/server/apps/trak/urls.py
@@ -16,8 +16,8 @@
         include(
             [
                 # Manifest
+                path("manifest", CreateRcraManifestView.as_view()),
                 path("manifest/<str:mtn>", ManifestView.as_view()),
-                path("manifest/create", CreateRcraManifestView.as_view()),
                 path("manifest/sign", SignManifestView.as_view()),
                 path("manifest/sync", SyncSiteManifestView.as_view()),
                 # MTN
diff --git a/server/apps/trak/views/manifest_view.py b/server/apps/trak/views/manifest_view.py
index 5b6b2efab..dc5ff887c 100644
--- a/server/apps/trak/views/manifest_view.py
+++ b/server/apps/trak/views/manifest_view.py
@@ -3,8 +3,8 @@
 from celery.exceptions import TaskError
 from celery.result import AsyncResult
 from django.db.models import Q
-from drf_spectacular.utils import extend_schema
-from rest_framework import status
+from drf_spectacular.utils import extend_schema, inline_serializer
+from rest_framework import serializers, status
 from rest_framework.generics import GenericAPIView, ListAPIView, RetrieveAPIView
 from rest_framework.request import Request
 from rest_framework.response import Response
@@ -86,15 +86,24 @@ def post(self, request: Request) -> Response:
             return Response(status=status.HTTP_500_INTERNAL_SERVER_ERROR, data=exc)
 
 
+@extend_schema(
+    request=inline_serializer(
+        "site_manifest_sync_request", fields={"siteId": serializers.CharField()}
+    ),
+    responses=inline_serializer(
+        "site_manifest_sync_response", fields={"task": serializers.CharField()}
+    ),
+)
 class SyncSiteManifestView(GenericAPIView):
     """
-    This endpoint launches a task to pull a site's manifests that are out of sync with RCRAInfo
+    Pull a site's manifests that are out of sync with RCRAInfo.
+    It returns the task id of the long-running background task which can be used to poll
+    for status.
     """
 
     queryset = None
 
     def post(self, request: Request) -> Response:
-        """POST method rcra_site"""
         try:
             site_id = request.data["siteId"]
             task = sync_site_manifests.delay(site_id=site_id, username=str(request.user))
@@ -105,9 +114,10 @@ def post(self, request: Request) -> Response:
             )
 
 
+@extend_schema(request=ManifestSerializer)
 class CreateRcraManifestView(GenericAPIView):
     """
-    This is a proxy endpoint used to create electronic manifest(s) in RCRAInfo/e-Manifest
+    A proxy endpoint used to create electronic manifest(s) in RCRAInfo/e-Manifest
     """
 
     queryset = None
@@ -115,7 +125,6 @@ class CreateRcraManifestView(GenericAPIView):
     http_method_names = ["post"]
 
     def post(self, request: Request) -> Response:
-        """The Body of the POST request should contain the complete and valid manifest object"""
         manifest_serializer = self.serializer_class(data=request.data)
         if manifest_serializer.is_valid():
             logger.debug(