docs(api): fix API response samples (#8592)

api/src/backend/api/schema_hooks.py

@@ -0,0 +1,95 @@
+def _pick_task_response_component(components):
+    schemas = components.get("schemas", {}) or {}
+    for candidate in ("TaskResponse",):
+        if candidate in schemas:
+            return candidate
+    return None
+
+
+def _extract_task_example_from_components(components):
+    schemas = components.get("schemas", {}) or {}
+    candidate = "TaskResponse"
+    doc = schemas.get(candidate)
+    if isinstance(doc, dict) and "example" in doc:
+        return doc["example"]
+
+    res = schemas.get(candidate)
+    if isinstance(res, dict) and "example" in res:
+        example = res["example"]
+        return example if "data" in example else {"data": example}
+
+    # Fallback
+    return {
+        "data": {
+            "type": "tasks",
+            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
+            "attributes": {
+                "inserted_at": "2019-08-24T14:15:22Z",
+                "completed_at": "2019-08-24T14:15:22Z",
+                "name": "string",
+                "state": "available",
+                "result": None,
+                "task_args": None,
+                "metadata": None,
+            },
+        }
+    }
+
+
+def attach_task_202_examples(result, generator, request, public):  # noqa: F841
+    if not isinstance(result, dict):
+        return result
+
+    components = result.get("components", {}) or {}
+    task_resp_component = _pick_task_response_component(components)
+    task_example = _extract_task_example_from_components(components)
+
+    paths = result.get("paths", {}) or {}
+    for path_item in paths.values():
+        if not isinstance(path_item, dict):
+            continue
+
+        for method_obj in path_item.values():
+            if not isinstance(method_obj, dict):
+                continue
+
+            responses = method_obj.get("responses", {}) or {}
+            resp_202 = responses.get("202")
+            if not isinstance(resp_202, dict):
+                continue
+
+            content = resp_202.get("content", {}) or {}
+            jsonapi = content.get("application/vnd.api+json")
+            if not isinstance(jsonapi, dict):
+                continue
+
+            # Inject example if missing
+            if "examples" not in jsonapi and "example" not in jsonapi:
+                jsonapi["examples"] = {
+                    "Task queued": {
+                        "summary": "Task queued",
+                        "value": task_example,
+                    }
+                }
+
+            # Rewrite schema $ref if needed
+            if task_resp_component:
+                schema = jsonapi.get("schema")
+                must_replace = False
+                if not isinstance(schema, dict):
+                    must_replace = True
+                else:
+                    ref = schema.get("$ref")
+                    if not ref:
+                        must_replace = True
+                    else:
+                        current = ref.split("/")[-1]
+                        if current != task_resp_component:
+                            must_replace = True
+
+                if must_replace:
+                    jsonapi["schema"] = {
+                        "$ref": f"#/components/schemas/{task_resp_component}"
+                    }
+
+    return result

api/src/backend/api/v1/views.py

@@ -308,23 +308,48 @@ class SchemaView(SpectacularAPIView):
                 "name": "Tenant",
                 "description": "Endpoints for managing tenants, along with their memberships.",
             },
+            {
+                "name": "Membership",
+                "description": "Endpoints for managing tenant memberships, allowing retrieval and filtering of "
+                "user membership information within tenants.",
+            },
             {
                 "name": "Invitation",
                 "description": "Endpoints for tenant invitations management, allowing retrieval and filtering of "
                 "invitations, creating new invitations, accepting and revoking them.",
             },
+            {
+                "name": "Role",
+                "description": "Endpoints for managing RBAC roles within tenants, allowing creation, retrieval, "
+                "updating, and deletion of role configurations and permissions.",
+            },
             {
                 "name": "Provider",
                 "description": "Endpoints for managing providers (AWS, GCP, Azure, etc...).",
             },
+            {
+                "name": "Provider Secret",
+                "description": "Endpoints for managing provider secrets, allowing secure storage and management "
+                "of credentials for providers.",
+            },
             {
                 "name": "Provider Group",
                 "description": "Endpoints for managing provider groups.",
             },
+            {
+                "name": "Task",
+                "description": "Endpoints for task management, allowing retrieval of task status and "
+                "revoking tasks that have not started.",
+            },
             {
                 "name": "Scan",
                 "description": "Endpoints for triggering manual scans and viewing scan results.",
             },
+            {
+                "name": "Schedule",
+                "description": "Endpoints for managing scan schedules, allowing configuration of automated "
+                "scans with different scheduling options.",
+            },
             {
                 "name": "Resource",
                 "description": "Endpoints for managing resources discovered by scans, allowing "
@@ -336,8 +361,9 @@ class SchemaView(SpectacularAPIView):
                 "findings that result from scans.",
             },
             {
-                "name": "Overview",
-                "description": "Endpoints for retrieving aggregated summaries of resources from the system.",
+                "name": "Processor",
+                "description": "Endpoints for managing post-processors used to process Prowler findings, including "
+                "registration, configuration, and deletion of post-processing actions.",
             },
             {
                 "name": "Compliance Overview",
@@ -345,9 +371,8 @@ class SchemaView(SpectacularAPIView):
                 " compliance framework ID.",
             },
             {
-                "name": "Task",
-                "description": "Endpoints for task management, allowing retrieval of task status and "
-                "revoking tasks that have not started.",
+                "name": "Overview",
+                "description": "Endpoints for retrieving aggregated summaries of resources from the system.",
             },
             {
                 "name": "Integration",
@@ -357,12 +382,13 @@ class SchemaView(SpectacularAPIView):
             {
                 "name": "Lighthouse",
                 "description": "Endpoints for managing Lighthouse configurations, including creation, retrieval, "
-                "updating, and deletion of configurations such as OpenAI keys, models, and business context.",
+                "updating, and deletion of configurations such as OpenAI keys, models, and business "
+                "context.",
             },
             {
-                "name": "Processor",
-                "description": "Endpoints for managing post-processors used to process Prowler findings, including "
-                "registration, configuration, and deletion of post-processing actions.",
+                "name": "SAML",
+                "description": "Endpoints for Single Sign-On authentication management via SAML for seamless user "
+                "authentication.",
             },
         ]
         return super().get(request, *args, **kwargs)
@@ -3033,7 +3059,9 @@ class RoleProviderGroupRelationshipView(RelationshipView, BaseRLSViewSet):
                 description="Compliance overviews metadata obtained successfully",
                 response=ComplianceOverviewMetadataSerializer,
             ),
-            202: OpenApiResponse(description="The task is in progress"),
+            202: OpenApiResponse(
+                description="The task is in progress", response=TaskSerializer
+            ),
             500: OpenApiResponse(
                 description="Compliance overviews generation task failed"
             ),
@@ -3065,7 +3093,9 @@ class RoleProviderGroupRelationshipView(RelationshipView, BaseRLSViewSet):
                 description="Compliance requirement details obtained successfully",
                 response=ComplianceOverviewDetailSerializer(many=True),
             ),
-            202: OpenApiResponse(description="The task is in progress"),
+            202: OpenApiResponse(
+                description="The task is in progress", response=TaskSerializer
+            ),
             500: OpenApiResponse(
                 description="Compliance overviews generation task failed"
             ),

api/src/backend/config/django/base.py

@@ -116,6 +116,9 @@ SPECTACULAR_SETTINGS = {
     "PREPROCESSING_HOOKS": [
         "drf_spectacular_jsonapi.hooks.fix_nested_path_parameters",
     ],
+    "POSTPROCESSING_HOOKS": [
+        "api.schema_hooks.attach_task_202_examples",
+    ],
     "TITLE": "API Reference - Prowler",
 }