Improve API Documentation

[Carrington-dev]

Description

API endpoints lack comprehensive documentation with examples and response formats.

Tasks

• Add docstrings to all API viewsets
• Generate OpenAPI/Swagger documentation
• Add request/response examples
• Document error responses
• Add authentication documentation
• Add rate limiting documentation
• Create Postman collection
• Add API versioning documentation

Implementation

from drf_yasg.utils import swagger_auto_schema
from drf_yasg import openapi

class PayFastPaymentModelViewSet(ModelViewSet):
    """
    PayFast Payment API
    
    Provides endpoints for creating and managing PayFast payments.
    """
    
    @swagger_auto_schema(
        operation_description="Create a new payment",
        request_body=PayFastPaymentCreateSerializer,
        responses={
            201: PayFastPaymentDetailSerializer,
            400: "Bad Request - Validation errors",
            429: "Too Many Requests - Rate limit exceeded"
        }
    )
    def create(self, request, *args, **kwargs):
        """
        Create a new PayFast payment.
        
        Example request:
        {
            "amount": "99.99",
            "item_name": "Premium Subscription",
            "email_address": "user@example.com"
        }
        
        Returns payment object with payfast_url for redirect.
        """
        return super().create(request, *args, **kwargs)

Acceptance Criteria

• All endpoints documented
• Swagger UI available
• Examples for all operations
• Postman collection provided