docs: add OpenAPI responses={} to all router endpoints

Add explicit HTTP status code documentation to every endpoint
across 15 router files. Each endpoint now declares all possible
response codes (200/201/204/400/401/404/409/429/502/503) with
descriptions so frontend can distinguish error types.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/routers/blocklist.py

@@ -97,6 +97,10 @@ def _check_blocklist_import_rate_limit(
     "",
     response_model=BlocklistListResponse,
     summary="List all blocklist sources",
+    responses={
+        200: {"description": "Blocklist sources returned", "model": BlocklistListResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+    },
 )
 async def list_blocklists(
     blocklist_ctx: BlocklistServiceContextDep,
@@ -120,6 +124,11 @@ async def list_blocklists(
     response_model=BlocklistSource,
     status_code=status.HTTP_201_CREATED,
     summary="Add a new blocklist source",
+    responses={
+        201: {"description": "Blocklist source created", "model": BlocklistSource},
+        400: {"description": "URL validation failed"},
+        401: {"description": "Session missing, expired, or invalid"},
+    },
 )
 async def create_blocklist(
     payload: BlocklistSourceCreate,
@@ -157,6 +166,11 @@ async def create_blocklist(
     response_model=ImportRunResult,
     summary="Trigger a manual blocklist import",
     dependencies=[Depends(_check_blocklist_import_rate_limit)],
+    responses={
+        200: {"description": "Import completed", "model": ImportRunResult},
+        401: {"description": "Session missing, expired, or invalid"},
+        429: {"description": "Rate limit exceeded for blocklist import"},
+    },
 )
 async def run_import_now(
     http_session: HttpSessionDep,
@@ -193,6 +207,10 @@ async def run_import_now(
     "/schedule",
     response_model=ScheduleInfo,
     summary="Get the current import schedule",
+    responses={
+        200: {"description": "Schedule info returned", "model": ScheduleInfo},
+        401: {"description": "Session missing, expired, or invalid"},
+    },
 )
 async def get_schedule(
     blocklist_ctx: BlocklistServiceContextDep,
@@ -219,6 +237,10 @@ async def get_schedule(
     "/schedule",
     response_model=ScheduleInfo,
     summary="Update the import schedule",
+    responses={
+        200: {"description": "Schedule updated", "model": ScheduleInfo},
+        401: {"description": "Session missing, expired, or invalid"},
+    },
 )
 async def update_schedule(
     payload: ScheduleConfig,
@@ -255,6 +277,10 @@ async def update_schedule(
     "/log",
     response_model=ImportLogListResponse,
     summary="Get the paginated import log",
+    responses={
+        200: {"description": "Import log returned", "model": ImportLogListResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+    },
 )
 async def get_import_log(
     blocklist_ctx: BlocklistServiceContextDep,
@@ -291,6 +317,11 @@ async def get_import_log(
     "/{source_id}",
     response_model=BlocklistSource,
     summary="Get a single blocklist source",
+    responses={
+        200: {"description": "Blocklist source returned", "model": BlocklistSource},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Blocklist source not found"},
+    },
 )
 async def get_blocklist(
     source_id: int,
@@ -317,6 +348,12 @@ async def get_blocklist(
     "/{source_id}",
     response_model=BlocklistSource,
     summary="Update a blocklist source",
+    responses={
+        200: {"description": "Blocklist source updated", "model": BlocklistSource},
+        400: {"description": "URL validation failed"},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Blocklist source not found"},
+    },
 )
 async def update_blocklist(
     source_id: int,
@@ -355,6 +392,11 @@ async def update_blocklist(
     "/{source_id}",
     status_code=status.HTTP_204_NO_CONTENT,
     summary="Delete a blocklist source",
+    responses={
+        204: {"description": "Blocklist source deleted successfully"},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Blocklist source not found"},
+    },
 )
 async def delete_blocklist(
     source_id: int,
@@ -380,6 +422,12 @@ async def delete_blocklist(
     "/{source_id}/preview",
     response_model=PreviewResponse,
     summary="Preview the contents of a blocklist source",
+    responses={
+        200: {"description": "Blocklist preview returned", "model": PreviewResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Blocklist source not found"},
+        502: {"description": "URL could not be reached"},
+    },
 )
 async def preview_blocklist(
     source_id: int,