🩹(schema) create request/response serializers

... for OrderViewSet
t s
Each viewset endpoints take and send differentes values.
It's currently defined as Order for all ViewSet endpoints.

Here we specify which data will be given in the request body
and which data will be sent as response.

Author: rlecellier

src/backend/joanie/core/api.py

@@ -114,9 +114,7 @@ def get_serializer_context(self):
         return context
 
     @swagger_auto_schema(
-        manual_parameters=[
-            openapi.Parameter("course", in_=openapi.IN_QUERY, type=openapi.TYPE_STRING)
-        ],
+        query_serializer=serializers.ProductRetrieveQuerySerializer,
     )
     def retrieve(self, *args, **kwargs):
         return super().retrieve(*args, **kwargs)
@@ -186,6 +184,10 @@ def perform_create(self, serializer):
         owner = User.update_or_create_from_request_user(request_user=self.request.user)
         serializer.save(owner=owner)
 
+    @swagger_auto_schema(
+        request_body=serializers.OrderCreateBodySerializer,
+        responses={201: serializers.OrderCreateResponseSerializer},
+    )
     @transaction.atomic
     def create(self, request, *args, **kwargs):
         """Try to create an order and a related payment if the payment is fee."""
@@ -257,12 +259,17 @@ def create(self, request, *args, **kwargs):
 
             # Return the fresh new order with payment_info
             return Response(
-                {**serializer.data, "payment_info": payment_info}, status=201
+                {**serializer.data, "payment_info": payment_info},
+                status=201,
             )
 
         # Else return the fresh new order
         return Response(serializer.data, status=201)
 
+    @swagger_auto_schema(
+        request_body=serializers.OrderAbortBodySerializer,
+        responses={204: serializers.EmptyResponseSerializer},
+    )
     @action(detail=True, methods=["POST"])
     def abort(self, request, pk=None):  # pylint: disable=no-self-use, invalid-name
         """Abort a pending order and the related payment if there is one."""
@@ -287,6 +294,17 @@ def abort(self, request, pk=None):  # pylint: disable=no-self-use, invalid-name
 
         return Response(status=204)
 
+    @swagger_auto_schema(
+        query_serializer=serializers.OrderInvoiceQuerySerializer,
+        responses={
+            200: openapi.Response(
+                "File Attachment", schema=openapi.Schema(type=openapi.TYPE_FILE)
+            ),
+            400: serializers.ErrorResponseSerializer,
+            404: serializers.ErrorResponseSerializer,
+        },
+        produces="application/pdf",
+    )
     @action(detail=True, methods=["GET"])
     def invoice(self, request, pk=None):  # pylint: disable=no-self-use, invalid-name
         """
@@ -400,6 +418,16 @@ def get_queryset(self):
         user = User.update_or_create_from_request_user(request_user=self.request.user)
         return models.Certificate.objects.filter(order__owner=user)
 
+    @swagger_auto_schema(
+        responses={
+            200: openapi.Response(
+                "File Attachment", schema=openapi.Schema(type=openapi.TYPE_FILE)
+            ),
+            404: serializers.ErrorResponseSerializer,
+            422: serializers.ErrorResponseSerializer,
+        },
+        produces="application/pdf",
+    )
     @action(detail=True, methods=["GET"])
     def download(self, request, pk=None):  # pylint: disable=no-self-use, invalid-name
         """

src/backend/joanie/core/serializers/__init__.py

@@ -0,0 +1,8 @@
+from .model_serializers import *
+from .empty_response_serializer import *
+from .error_response_serializer import *
+from .order_create_body_serializer import *
+from .order_create_response_serializer import *
+from .order_abort_body_serializer import *
+from .order_invoice_query_serializer import *
+from .product_retrieve_query_serializer import *

src/backend/joanie/core/serializers/empty_response_serializer.py

@@ -0,0 +1,7 @@
+"""Serializers for empty Response"""
+
+from rest_framework import serializers
+
+
+class EmptyResponseSerializer(serializers.Serializer):
+    pass

src/backend/joanie/core/serializers/error_response_serializer.py

@@ -0,0 +1,10 @@
+"""Serializers for core.api.OrderViewSet.abort Body"""
+
+from rest_framework import serializers
+
+
+class ErrorResponseSerializer(serializers.Serializer):
+    details = serializers.CharField(required=True)
+
+    class Meta:
+        fields = ["details"]

src/backend/joanie/core/serializers.py renamed to src/backend/joanie/core/serializers/model_serializers.py

@@ -1,4 +1,4 @@
-"""Serializers for api."""
+"""Serializers for core.models"""
 
 from django.conf import settings
 from django.core.cache import cache
@@ -7,8 +7,7 @@
 from rest_framework import serializers
 
 from joanie.core import models, utils
-
-from .enums import ORDER_STATE_PENDING, ORDER_STATE_VALIDATED
+from joanie.core.enums import ORDER_STATE_PENDING, ORDER_STATE_VALIDATED
 
 
 class CertificationDefinitionSerializer(serializers.ModelSerializer):
@@ -545,3 +544,10 @@ class Meta:
         model = models.Certificate
         fields = ["id"]
         read_only_fields = ["id"]
+
+
+class PaymentSerializer(serializers.Serializer):
+    payment_id = serializers.CharField(required=True)
+    provider = serializers.CharField(required=True)
+    url = serializers.CharField(required=True)
+    is_paid = serializers.BooleanField(required=False)

src/backend/joanie/core/serializers/order_abort_body_serializer.py

@@ -0,0 +1,12 @@
+"""Serializers for core.api.OrderViewSet.abort Body"""
+
+from rest_framework import serializers
+
+from .model_serializers import OrderSerializer, AddressSerializer
+
+
+class OrderAbortBodySerializer(serializers.Serializer):
+    payment_id = serializers.CharField(required=True)
+
+    class Meta:
+        fields = ["payment_id"]

src/backend/joanie/core/serializers/order_abort_response_serializer.py

@@ -0,0 +1,14 @@
+"""Serializers for core.api.OrderViewSet.create Response"""
+
+from rest_framework import serializers
+
+from .model_serializers import OrderSerializer, PaymentSerializer
+
+
+class OrderAbortResponseSerializer(OrderSerializer):
+    id = serializers.CharField(required=True)
+    payment_info = PaymentSerializer(required=False)
+
+    class Meta(OrderSerializer.Meta):
+        fields = OrderSerializer.Meta.fields + ["payment_info"]
+        read_only_fields = OrderSerializer.Meta.fields + ["payment_info"]

src/backend/joanie/core/serializers/order_create_body_serializer.py

@@ -0,0 +1,11 @@
+"""Serializers for core.api.OrderViewSet.create Body"""
+
+from .model_serializers import OrderSerializer, AddressSerializer
+
+
+class OrderCreateBodySerializer(OrderSerializer):
+    billing_address = AddressSerializer(required=False)
+
+    class Meta(OrderSerializer.Meta):
+        fields = OrderSerializer.Meta.fields + ["billing_address"]
+        read_only_fields = OrderSerializer.Meta.fields + ["billing_address"]

src/backend/joanie/core/serializers/order_create_response_serializer.py

@@ -0,0 +1,14 @@
+"""Serializers for core.api.OrderViewSet.create Response"""
+
+from rest_framework import serializers
+
+from .model_serializers import OrderSerializer, PaymentSerializer
+
+
+class OrderCreateResponseSerializer(OrderSerializer):
+    id = serializers.CharField(required=True)
+    payment_info = PaymentSerializer(required=False)
+
+    class Meta(OrderSerializer.Meta):
+        fields = OrderSerializer.Meta.fields + ["payment_info"]
+        read_only_fields = OrderSerializer.Meta.fields + ["payment_info"]

src/backend/joanie/core/serializers/order_invoice_query_serializer.py

@@ -0,0 +1,10 @@
+"""Serializers for core.api.OrderViewSet.abort Body"""
+
+from rest_framework import serializers
+
+
+class OrderInvoiceQuerySerializer(serializers.Serializer):
+    reference = serializers.CharField(required=True)
+
+    class Meta:
+        fields = ["reference"]