From 8afbcee04d63cab48f093160927b325985c38c70 Mon Sep 17 00:00:00 2001
From: stumpylog <797416+stumpylog@users.noreply.github.com>
Date: Fri, 17 Apr 2026 11:52:07 -0700
Subject: [PATCH] fix: annotate tasks_summary_retrieve as array of
 TaskSummarySerializer

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/documents/tests/test_api_schema.py | 36 ++++++++++++++++++++++++++
 src/documents/views.py                 |  1 +
 2 files changed, 37 insertions(+)

diff --git a/src/documents/tests/test_api_schema.py b/src/documents/tests/test_api_schema.py
index d8b023e6a..4e44963de 100644
--- a/src/documents/tests/test_api_schema.py
+++ b/src/documents/tests/test_api_schema.py
@@ -1,5 +1,7 @@
+import pytest
 from django.core.management import call_command
 from django.core.management.base import CommandError
+from drf_spectacular.generators import SchemaGenerator
 from rest_framework import status
 from rest_framework.test import APITestCase
 
@@ -66,3 +68,37 @@ class TestApiSchema(APITestCase):
             "delete_pages",
         ]:
             self.assertIn(action_method, advertised_methods)
+
+
+# ---- session-scoped fixture: generate schema once for all TestXxx classes ----
+
+
+@pytest.fixture(scope="session")
+def api_schema():
+    generator = SchemaGenerator()
+    return generator.get_schema(request=None, public=True)
+
+
+class TestTasksSummarySchema:
+    """tasks_summary_retrieve: response must be an array of TaskSummarySerializer."""
+
+    def test_summary_response_is_array(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/summary/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        assert resp_200["type"] == "array", (
+            "tasks_summary_retrieve response must be type:array"
+        )
+
+    def test_summary_items_have_total_count(self, api_schema):
+        op = api_schema["paths"]["/api/tasks/summary/"]["get"]
+        resp_200 = op["responses"]["200"]["content"]["application/json"]["schema"]
+        items = resp_200.get("items", {})
+        ref = items.get("$ref", "")
+        component_name = ref.split("/")[-1] if ref else ""
+        if component_name:
+            props = api_schema["components"]["schemas"][component_name]["properties"]
+        else:
+            props = items.get("properties", {})
+        assert "total_count" in props, (
+            "summary items must have 'total_count' (TaskSummarySerializer)"
+        )
diff --git a/src/documents/views.py b/src/documents/views.py
index 43fbf7a03..104999987 100644
--- a/src/documents/views.py
+++ b/src/documents/views.py
@@ -3784,6 +3784,7 @@ class RemoteVersionView(GenericAPIView[Any]):
         },
     ),
     summary=extend_schema(
+        responses={200: TaskSummarySerializer(many=True)},
         parameters=[
             OpenApiParameter(
                 name="days",