Refine the generated schema for CollectViewSet

Signed-off-by: Keshav Priyadarshi <[email protected]>

packagedb/api.py

@@ -39,6 +39,10 @@
                                    PackageAPISerializer,
                                    PackageSetAPISerializer, PartySerializer,
                                    ResourceAPISerializer)
+from drf_spectacular.utils import extend_schema
+from drf_spectacular.utils import OpenApiParameter
+from packagedb.serializers import IndexPackagesSerializer
+from packagedb.serializers import IndexPackagesResponseSerializer
 
 logger = logging.getLogger(__name__)
 
@@ -517,10 +521,13 @@ class CollectViewSet(viewsets.ViewSet):
     If the package does not exist, we will fetch the Package data and return
     it in the same request.
     
-    **Note:** Use `Index packages` for bulk indexing of packages; use `Reindex packages`
-    for bulk reindexing of existing packages.
+    **Note:** Use `Index packages` for bulk indexing/reindexing of packages.
     """
-
+    serializer_class=None
+    @extend_schema(
+            parameters=[OpenApiParameter('purl', str, 'query', description='PackageURL')],
+            responses={200:PackageAPISerializer()},
+    )
     def list(self, request, format=None):
         purl = request.query_params.get('purl')
 
@@ -550,14 +557,20 @@ def list(self, request, format=None):
                 message = {}
                 if errors:
                     message = {
-                        'status': f'error(s) occured when fetching metadata for {purl}: {errors}'
+                        'status': f'error(s) occurred when fetching metadata for {purl}: {errors}'
                     }
                 return Response(message)
 
         serializer = PackageAPISerializer(packages, many=True, context={'request': request})
         return Response(serializer.data)
 
-    @action(detail=False, methods=['post'])
+    @extend_schema(
+        request=IndexPackagesSerializer,
+        responses={
+            200: IndexPackagesResponseSerializer(),
+        },
+    )
+    @action(detail=False, methods=['post'], serializer_class=IndexPackagesSerializer)
     def index_packages(self, request, *args, **kwargs):
         """
         Take a list of `packages` (where each item is a dictionary containing either PURL
@@ -570,7 +583,7 @@ def index_packages(self, request, *args, **kwargs):
         **Note:** When a versionless PURL is supplied without a vers range, then all the versions
         of that package will be considered for indexing/reindexing.
 
-        **Input example:**
+        **Request example:**
 
                 {
                     "packages": [
@@ -623,9 +636,15 @@ def _reindex_package(package, reindexed_packages):
             package.rescan()
             reindexed_packages.append(package)
 
-        packages = request.data.get('packages') or []
-        reindex = request.data.get('reindex') or False
-        reindex_set = request.data.get('reindex_set') or False
+        serializer = self.serializer_class(data=request.data)
+
+        if not serializer.is_valid():
+            return Response({'errors': serializer.errors}, status=400)
+
+        validated_data = serializer.validated_data
+        packages = validated_data.get('packages', [])
+        reindex = validated_data.get('reindex', False)
+        reindex_set = validated_data.get('reindex_set', False)
 
         queued_packages = []
         unqueued_packages = []
@@ -679,7 +698,9 @@ def _reindex_package(package, reindexed_packages):
             'unsupported_vers_count': len(unsupported_vers),
             'unsupported_vers': unsupported_vers,
         }
-        return Response(response_data)
+
+        serializer = IndexPackagesResponseSerializer(response_data, context={'request': request})
+        return Response(serializer.data)
 
 
 def get_resolved_purls(packages, supported_ecosystems):

packagedb/serializers.py

@@ -10,12 +10,16 @@
 from django.http import HttpRequest
 from django.urls import reverse_lazy
 
+from rest_framework.serializers import BooleanField
 from rest_framework.serializers import CharField
 from rest_framework.serializers import HyperlinkedIdentityField
 from rest_framework.serializers import HyperlinkedModelSerializer
 from rest_framework.serializers import HyperlinkedRelatedField
+from rest_framework.serializers import IntegerField
 from rest_framework.serializers import JSONField
+from rest_framework.serializers import ListField
 from rest_framework.serializers import ModelSerializer
+from rest_framework.serializers import Serializer
 from rest_framework.serializers import SerializerMethodField
 
 from packagedb.models import DependentPackage
@@ -328,3 +332,42 @@ class Meta:
             'uuid',
             'packages',
         ]
+
+
+class PackageVersSerializer(Serializer):
+    purl = CharField()
+    vers = CharField(required=False)
+
+
+class IndexPackagesSerializer(Serializer):
+    packages = PackageVersSerializer(many=True)
+    reindex = BooleanField(default=False)
+    reindex_set = BooleanField(default=False)
+
+
+class IndexPackagesResponseSerializer(Serializer):
+    queued_packages_count = IntegerField(help_text="Number of package urls placed on the index queue.")
+    queued_packages = ListField(
+        child=CharField(),
+        help_text="List of package urls that were placed on the index queue."
+    )
+    requeued_packages_count = IntegerField(help_text="Number of existing package urls placed on the rescan queue.")
+    requeued_packages = ListField(
+        child=CharField(),
+        help_text="List of existing package urls that were placed on the rescan queue."
+    )
+    unqueued_packages_count = IntegerField(help_text="Number of package urls not placed on the index queue.")
+    unqueued_packages = ListField(
+        child=CharField(),
+        help_text="List of package urls that were not placed on the index queue."
+    )
+    unsupported_packages_count = IntegerField(help_text="Number of package urls that are not processable by the index queue.")
+    unsupported_packages = ListField(
+        child=CharField(),
+        help_text="List of package urls that are not processable by the index queue."
+    )
+    unsupported_vers_count = IntegerField(help_text="Number of vers range that are not supported by the univers or package_manager.")
+    unsupported_vers = ListField(
+        child=CharField(),
+        help_text="List of vers range that are not supported by the univers or package_manager."
+    )

purldb/urls.py

@@ -23,7 +23,7 @@
 from minecode.api import PriorityResourceURIViewSet
 from packagedb.api import CollectViewSet
 from drf_spectacular.views import SpectacularAPIView
-from drf_spectacular.views import SpectacularRedocView
+from drf_spectacular.views import SpectacularSwaggerView
 
 
 api_router = routers.DefaultRouter()
@@ -43,5 +43,5 @@
     path('api/', include((api_router.urls, 'api'))),
     path("", RedirectView.as_view(url="api/")),
     path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
-    path('api/docs/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
+    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
 ]