Fix OpenAPI schema for async responses

closes #3668
https://pulp.plan.io/issues/3668

plugin/pulpcore/plugin/serializers.py

@@ -1,5 +1,6 @@
 # Import Serializers in platform that are potentially useful to plugin writers
 from pulpcore.app.serializers import (  # NOQA
+    AsnycOperationResponseSerializer,
     ContentSerializer,
     RemoteSerializer,
     PublisherSerializer,

pulpcore/pulpcore/app/serializers/__init__.py

@@ -3,7 +3,8 @@
 # - all can import directly from base and fields if needed
 from pulpcore.app.serializers.base import (DetailRelatedField, GenericKeyValueRelatedField,  # noqa
     ModelSerializer, MasterModelSerializer, DetailIdentityField, DetailRelatedField,
-    view_name_for_model, viewset_for_model, validate_unknown_fields)
+    view_name_for_model, viewset_for_model, validate_unknown_fields,
+    AsnycOperationResponseSerializer)
 from pulpcore.app.serializers.fields import (BaseURLField, ContentRelatedField,  # noqa
                                              LatestVersionField)
 from pulpcore.app.serializers.content import ContentSerializer, ArtifactSerializer  # noqa

pulpcore/pulpcore/app/serializers/base.py

@@ -382,3 +382,15 @@ def use_pk_only_optimization(self):
         class to get the relevant `view_name`.
         """
         return False
+
+
+class AsnycOperationResponseSerializer(serializers.Serializer):
+    """
+    Serializer for asynchronous operations.
+    """
+    _href = serializers.URLField(
+        help_text=_('URL to a task.')
+    )
+    task_id = serializers.UUIDField(
+        help_text=_('Task UUID')
+    )

pulpcore/pulpcore/app/viewsets/base.py

@@ -6,11 +6,14 @@
 from pulpcore.app import tasks
 from pulpcore.app.models import MasterModel
 from pulpcore.app.response import OperationPostponedResponse
+from pulpcore.app.serializers import AsnycOperationResponseSerializer
 from pulpcore.tasking.tasks import enqueue_with_reservation
 
 from django.urls import resolve, Resolver404
 from django.core.exceptions import FieldError, ValidationError
 
+from drf_yasg.utils import swagger_auto_schema
+
 from rest_framework import viewsets
 from rest_framework.generics import get_object_or_404
 from rest_framework.schemas import AutoSchema
@@ -257,6 +260,8 @@ class AsyncUpdateMixin:
     Provides an update method that dispatches a task with reservation for the instance
     """
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous update task",
+                         responses={202: AsnycOperationResponseSerializer})
     def update(self, request, pk, **kwargs):
         partial = kwargs.pop('partial', False)
         instance = self.get_object()
@@ -270,6 +275,8 @@ def update(self, request, pk, **kwargs):
         )
         return OperationPostponedResponse(async_result, request)
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous partial update task",
+                         responses={202: AsnycOperationResponseSerializer})
     def partial_update(self, request, *args, **kwargs):
         kwargs['partial'] = True
         return self.update(request, *args, **kwargs)
@@ -280,6 +287,8 @@ class AsyncRemoveMixin:
     Provides a delete method that dispatches a task with reservation for the instance
     """
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous delete task",
+                         responses={202: AsnycOperationResponseSerializer})
     def destroy(self, request, pk, **kwargs):
         """
         Delete a model instance

pulpcore/pulpcore/app/viewsets/repository.py

@@ -3,7 +3,6 @@
 
 from django_filters.rest_framework import filters, filterset, DjangoFilterBackend
 from django_filters import Filter
-
 from drf_yasg.utils import swagger_auto_schema
 
 from rest_framework import decorators, mixins, serializers
@@ -24,6 +23,7 @@
 from pulpcore.app.pagination import UUIDPagination, NamePagination
 from pulpcore.app.response import OperationPostponedResponse
 from pulpcore.app.serializers import (
+    AsnycOperationResponseSerializer,
     ContentSerializer,
     DistributionSerializer,
     ExporterSerializer,
@@ -59,6 +59,9 @@ class RepositoryViewSet(NamedModelViewSet,
     pagination_class = NamePagination
     filter_class = RepositoryFilter
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous task to update"
+                                               "a repository.",
+                         responses={202: AsnycOperationResponseSerializer})
     def update(self, request, pk, partial=False):
         """
         Generates a Task to update a Repository
@@ -73,6 +76,9 @@ def update(self, request, pk, partial=False):
         )
         return OperationPostponedResponse(async_result, request)
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous task to delete a "
+                                               "repository.",
+                         responses={202: AsnycOperationResponseSerializer})
     def destroy(self, request, pk):
         """
         Generates a Task to delete a Repository
@@ -233,6 +239,9 @@ def _paginated_response(self, content, request):
         serializer = ContentSerializer(page, many=True, context={'request': request})
         return paginator.get_paginated_response(serializer.data)
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous task to delete "
+                                               "a repositroy version.",
+                         responses={202: AsnycOperationResponseSerializer})
     def destroy(self, request, repository_pk, number):
         """
         Queues a task to handle deletion of a RepositoryVersion
@@ -244,6 +253,9 @@ def destroy(self, request, repository_pk, number):
         )
         return OperationPostponedResponse(async_result, request)
 
+    @swagger_auto_schema(operation_description="Trigger an asynchronous task to create "
+                                               "a new repository version.",
+                         responses={202: AsnycOperationResponseSerializer})
     def create(self, request, repository_pk):
         """
         Queues a task that creates a new RepositoryVersion by adding and removing content units