Document off-cycle payment response schema

backend/api/v1/finance/admin/off_cycle.py

@@ -3,6 +3,7 @@ from decimal import Decimal
 from django.db.models import Q, Sum
 from django.shortcuts import get_object_or_404
 from django.utils import timezone
+from drf_spectacular.utils import extend_schema_field
 from rest_framework import serializers
 from rest_framework.response import Response
 
@@ -70,6 +71,13 @@ class PaymentWriteSerializer(serializers.Serializer):
         return attrs
 
 
+class PaymentSettlementSerializer(serializers.Serializer):
+    original_payable = serializers.CharField()
+    paid_outside_period = serializers.CharField()
+    remaining = serializers.CharField()
+    confirmed = serializers.BooleanField()
+
+
 class PaymentSerializer(serializers.ModelSerializer):
     settlement = serializers.SerializerMethodField()
     employee_id = serializers.IntegerField(read_only=True, allow_null=True)
@@ -78,14 +86,16 @@ class PaymentSerializer(serializers.ModelSerializer):
     created_by = PayrollUserRefSerializer(read_only=True)
     voided_by = PayrollUserRefSerializer(read_only=True, allow_null=True)
 
-    def get_source_period_name(self, obj):
+    @extend_schema_field(serializers.CharField(allow_null=True))
+    def get_source_period_name(self, obj) -> str | None:
         return (
             (obj.source_period.name or obj.source_period.code)
             if obj.source_period
             else None
         )
 
-    def get_settlement(self, obj):
+    @extend_schema_field(PaymentSettlementSerializer(allow_null=True))
+    def get_settlement(self, obj) -> dict | None:
         if not obj.source_statement_id:
             return None
         cache = self.context.setdefault("settlements", {})