Refine the generated schema for PurlValidateViewSet

Signed-off-by: Keshav Priyadarshi <git@keshav.space>

packagedb/api.py

@@ -39,6 +39,8 @@
                                    PackageAPISerializer,
                                    PackageSetAPISerializer, PartySerializer,
                                    ResourceAPISerializer)
+from packagedb.serializers import PurlValidateResponseSerializer
+from packagedb.serializers import PurlValidateSerializer
 from drf_spectacular.utils import extend_schema
 from drf_spectacular.utils import OpenApiParameter
 from packagedb.serializers import IndexPackagesSerializer
@@ -639,7 +641,7 @@ def _reindex_package(package, reindexed_packages):
         serializer = self.serializer_class(data=request.data)
 
         if not serializer.is_valid():
-            return Response({'errors': serializer.errors}, status=400)
+            return Response({'errors': serializer.errors}, status=status.HTTP_400_BAD_REQUEST)
 
         validated_data = serializer.validated_data
         packages = validated_data.get('packages', [])
@@ -702,7 +704,6 @@ def _reindex_package(package, reindexed_packages):
         serializer = IndexPackagesResponseSerializer(response_data, context={'request': request})
         return Response(serializer.data)
 
-
 class PurlValidateViewSet(viewsets.ViewSet):
     """
     Take a `purl` and check whether it's valid PackageURL or not.  
@@ -711,7 +712,7 @@ class PurlValidateViewSet(viewsets.ViewSet):
     **Note:** As of now `check_existence` only supports `apache`, `composer`, `deb`, `gem`, 
     `github`, `golang`, `maven`, `npm`, `nuget`and `pypi` ecosystems.
 
-    **Input example:**
+    **Request example:**
 
             {
                 "purl": "pkg:npm/foobar@12.3.1",
@@ -725,12 +726,27 @@ class PurlValidateViewSet(viewsets.ViewSet):
     - exists
         - True, if input PURL exists in real world and `check_existence` flag is enabled.
     """
+    serializer_class = PurlValidateSerializer
+
     def get_view_name(self):
         return 'Validate PURL'
-
+
+    @extend_schema(
+        parameters=[
+            OpenApiParameter('purl', str, 'query', description='PackageURL'),
+            OpenApiParameter('check_existence', bool, 'query', description='Check existence', default=False),
+        ],
+        responses={200: PurlValidateResponseSerializer()},
+    )
     def list(self, request):
-        purl = request.query_params.get("purl")
-        check_existence = request.query_params.get("check_existence") or False
+        serializer = self.serializer_class(data=request.query_params)
+
+        if not serializer.is_valid():
+            return Response({'errors': serializer.errors}, status=status.HTTP_400_BAD_REQUEST)
+
+        validated_data = serializer.validated_data
+        purl = validated_data.get('purl')
+        check_existence = validated_data.get('check_existence', False)
 
         message_valid = "The provided PackageURL is valid."
         message_not_valid = "The provided PackageURL is not valid."
@@ -743,6 +759,9 @@ def list(self, request):
         message_error_no_purl = (
             "PackageURL (purl) is required. Please provide a PackageURL in the request."
         )
+        response = {}
+        response['exists'] = None
+        response['purl'] = purl
 
         if not purl:
             return Response(
@@ -757,22 +776,19 @@ def list(self, request):
         try:
             package_url = PackageURL.from_string(purl)
         except ValueError:
-            return Response(
-                {
-                    "valid": False,
-                    "message": message_not_valid,
-                    "purl": purl,
-                }
-            )
+            response['valid'] = False
+            response['message'] = message_not_valid
+            serializer = PurlValidateResponseSerializer(response, context={'request': request})
+            return Response(serializer.data)
 
-        exists = None
-        message = message_valid
+        response['valid'] = True
+        response['message'] = message_valid
         if check_existence:
-            exists = False
+            response['exists'] = False
             lookups = purl_to_lookups(purl)
             packages = Package.objects.filter(**lookups)
             if packages.exists():
-                exists = True
+                response['exists'] = True
             else:
                 versionless_purl = PackageURL(
                     type=package_url.type,
@@ -785,17 +801,11 @@ def list(self, request):
                 ):
                     # True, if requested purl has no version and any version of package exists upstream.
                     # True, if requested purl.version exists upstream.
-                    exists = True
-            message = message_valid_and_exists if exists else message_valid_but_does_not_exist
+                    response['exists'] = True
+            response['message'] = message_valid_and_exists if response['exists'] else message_valid_but_does_not_exist
 
-        return Response(
-            {
-                "valid": True,
-                "exists": exists,
-                "message": message,
-                "purl": purl,
-            }
-        )
+        serializer = PurlValidateResponseSerializer(response, context={'request': request})
+        return Response(serializer.data)
 
 
 def get_resolved_purls(packages, supported_ecosystems):

packagedb/serializers.py

@@ -370,4 +370,14 @@ class IndexPackagesResponseSerializer(Serializer):
     unsupported_vers = ListField(
         child=CharField(),
         help_text="List of vers range that are not supported by the univers or package_manager."
-    )
+    )
+
+class PurlValidateResponseSerializer(Serializer):
+    valid = BooleanField()
+    exists = BooleanField(required=False)
+    message = CharField()
+    purl = CharField()
+
+class PurlValidateSerializer(Serializer):
+    purl = CharField()
+    check_existence = BooleanField(required=False, default=False)