chore: add openapi examples to seller's statistics endpoint and add d…

…ocstring

bid/openapi/seller_statistics_openapi_examples.py

@@ -0,0 +1,58 @@
+from drf_spectacular.openapi import OpenApiExample
+
+
+def seller_statistics_examples():
+    return [
+        OpenApiExample(
+            "Successful bid creation (POST)",
+            summary="Response for successfully fetching statistics",
+            description="This example demonstrates a successful response after seller "
+            "successfully fetches their statistics about bids.",
+            value={
+                "total_bids": 3000,
+                "total_auctions_participated": 3000,
+                "completed_auctions_participated": 2900,
+                "auctions_won": 500,
+                "live_auction_bids": 1800,
+                "success_rate": 79.50,
+            },
+            response_only=True,
+            status_codes=[200],
+        ),
+        OpenApiExample(
+            "Unauthorized user trying to create bid (POST)",
+            summary="Unauthorized user",
+            description="This example shows an unauthorized user trying to create a "
+            "bid without authentication.",
+            value={
+                "type": "client_error",
+                "errors": [
+                    {
+                        "code": "not_authenticated",
+                        "message": "Authentication credentials were not provided.",
+                        "field_name": None,
+                    }
+                ],
+            },
+            response_only=True,
+            status_codes=[401],
+        ),
+        OpenApiExample(
+            "Error: No permission. (GET)",
+            summary="No permission to view statistics.",
+            description="This example shows an error response when a user tries "
+            "to see statistics but they do not have a Seller type of user.",
+            value={
+                "type": "client_error",
+                "errors": [
+                    {
+                        "code": "permission_denied",
+                        "message": "You do not have permission to perform this action.",
+                        "field_name": None,
+                    }
+                ],
+            },
+            response_only=True,
+            status_codes=[403],
+        ),
+    ]

bid/serializers.py

@@ -318,3 +318,12 @@ def validate_bid_offer(self, new_offer, current_offer):
                     "the offer when updating a bid"
                 )
             )
+
+
+class SellerStatisticsSerializer(serializers.Serializer):
+    total_bids = serializers.IntegerField()
+    total_auctions_participated = serializers.IntegerField()
+    completed_auctions_participated = serializers.IntegerField()
+    auctions_won = serializers.IntegerField()
+    live_auction_bids = serializers.IntegerField()
+    success_rate = serializers.FloatField()

bid/views.py

@@ -26,6 +26,7 @@
 from bid.openapi.bid_reject_openapi_examples import reject_bid_examples
 from bid.openapi.bid_retrive_openapi_examples import retrieve_bid_examples
 from bid.openapi.bid_update_openapi_examples import update_bid_examples
+from bid.openapi.seller_statistics_openapi_examples import seller_statistics_examples
 from bid.permissions import (
     IsBidAuthorOrAuctionAuthor,
     IsBidOwner,
@@ -35,6 +36,7 @@
     BaseBidSerializer,
     BidListSerializer,
     CreateBidSerializer,
+    SellerStatisticsSerializer,
     UpdateBidSerializer,
 )
 
@@ -572,7 +574,33 @@ def list(self, request, *args, **kwargs):
             return Response(serializer.data)
 
 
+@extend_schema(
+    tags=["Statistics"],
+    examples=seller_statistics_examples(),
+    responses={
+        200: SellerStatisticsSerializer,
+        401: SellerStatisticsSerializer,
+        403: SellerStatisticsSerializer,
+    },
+)
 class SellerStatisticsView(generics.GenericAPIView):
+    """
+    View for retrieving seller statistics on auction participation and bids.
+
+    **Functionality**:
+    - Provides an overview of a seller's bidding activity and success in auctions.
+    - Calculates total bids, distinct auctions participated in, live auction bids,
+    completed auctions, auctions won, and success rate.
+    - Success rate reflects the percentage of completed auctions won by the seller.
+
+    **Permissions**:
+    - The user must be authenticated (IsAuthenticated).
+    - Only accessible to users with seller permissions (IsSeller).
+
+    **Response**:
+    - Returns a dictionary with bid and auction statistics.
+    """
+
     permission_classes = [IsAuthenticated, IsSeller]
 
     def get_stats(self, user_id):