[fix] Add dashboard API filters to browsable API docs #715

Added @swagger_auto_schema to DashboardTimeseriesView.get() to expose
query parameters (organization_slug, location_id, floorplan_id, time,
start, end, timezone, csv) in the Swagger/browsable API documentation.

Since DashboardTimeseriesView extends APIView and manually reads query
parameters from request.query_params, drf-yasg had no way to discover
them. The @swagger_auto_schema decorator explicitly declares these
parameters so they appear in the API docs.

Also added a regression test to verify the parameters are properly
declared.

Closes #715

Author: sargunn20

openwisp_monitoring/monitoring/api/views.py

@@ -1,5 +1,7 @@
 from cache_memoize import cache_memoize
 from django.db.models import Q
+from drf_yasg import openapi
+from drf_yasg.utils import swagger_auto_schema
 from rest_framework.exceptions import NotFound, PermissionDenied
 from rest_framework.permissions import IsAuthenticated
 from rest_framework.views import APIView
@@ -181,6 +183,64 @@ def _get_user_managed_orgs(self, request):
             return []
         return orgs
 
+    @swagger_auto_schema(
+        manual_parameters=[
+            openapi.Parameter(
+                "organization_slug",
+                openapi.IN_QUERY,
+                description="Comma-separated list of organization slugs",
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "location_id",
+                openapi.IN_QUERY,
+                description="Comma-separated list of location UUIDs",
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "floorplan_id",
+                openapi.IN_QUERY,
+                description="Comma-separated list of floorplan UUIDs",
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "time",
+                openapi.IN_QUERY,
+                description=(
+                    "Timeframe for chart data " "(e.g. 1d, 3d, 7d, 30d, 365d)"
+                ),
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "start",
+                openapi.IN_QUERY,
+                description=(
+                    "Start date/time in YYYY-MM-DD H:M:S format " '(use with "end")'
+                ),
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "end",
+                openapi.IN_QUERY,
+                description=(
+                    "End date/time in YYYY-MM-DD H:M:S format " '(use with "start")'
+                ),
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "timezone",
+                openapi.IN_QUERY,
+                description="Timezone name (e.g. UTC, Europe/Rome)",
+                type=openapi.TYPE_STRING,
+            ),
+            openapi.Parameter(
+                "csv",
+                openapi.IN_QUERY,
+                description="Set to export data as CSV",
+                type=openapi.TYPE_STRING,
+            ),
+        ]
+    )
     def get(self, request, *args, **kwargs):
         response = super().get(request, *args, **kwargs)
         if not request.GET.get("csv"):

openwisp_monitoring/monitoring/tests/test_api.py

@@ -724,3 +724,37 @@ def test_organizations_list(self):
                 response.data["organizations"],
                 [{"id": org.slug, "text": org.name} for org in [org1, org2]],
             )
+
+    def test_dashboard_api_filters_in_schema(self):
+        """Regression test for https://github.com/openwisp/openwisp-monitoring/issues/715
+
+        Verifies that DashboardTimeseriesView exposes the expected
+        query parameters via @swagger_auto_schema so they are
+        visible in the browsable API docs.
+        """
+        from openwisp_monitoring.monitoring.api.views import DashboardTimeseriesView
+
+        swagger_decorator = getattr(
+            DashboardTimeseriesView.get, "_swagger_auto_schema", None
+        )
+        self.assertIsNotNone(
+            swagger_decorator,
+            "DashboardTimeseriesView.get is missing @swagger_auto_schema",
+        )
+        manual_parameters = swagger_decorator.get("manual_parameters", [])
+        param_names = {p.name for p in manual_parameters}
+        expected_params = {
+            "organization_slug",
+            "location_id",
+            "floorplan_id",
+            "time",
+            "start",
+            "end",
+            "timezone",
+            "csv",
+        }
+        self.assertEqual(
+            param_names,
+            expected_params,
+            f"Missing or extra swagger parameters: {expected_params - param_names}",
+        )