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/jails.py

@@ -57,6 +57,11 @@ _NamePath = Annotated[str, Path(description="Jail name as configured in fail2ban
     "",
     response_model=JailListResponse,
     summary="List all active fail2ban jails",
+    responses={
+        200: {"description": "Jails list returned", "model": JailListResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def get_jails(
     _auth: AuthDep,
@@ -85,6 +90,12 @@ async def get_jails(
     "/{name}",
     response_model=JailDetailResponse,
     summary="Return full detail for a single jail",
+    responses={
+        200: {"description": "Jail detail returned", "model": JailDetailResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def get_jail(
     _auth: AuthDep,
@@ -129,6 +140,12 @@ async def get_jail(
     "/reload-all",
     response_model=JailCommandResponse,
     summary="Reload all fail2ban jails",
+    responses={
+        200: {"description": "All jails reloaded", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def reload_all_jails(
     _auth: AuthDep,
@@ -157,6 +174,13 @@ async def reload_all_jails(
     "/{name}/start",
     response_model=JailCommandResponse,
     summary="Start a stopped jail",
+    responses={
+        200: {"description": "Jail started", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def start_jail(
     _auth: AuthDep,
@@ -185,6 +209,12 @@ async def start_jail(
     "/{name}/stop",
     response_model=JailCommandResponse,
     summary="Stop a running jail",
+    responses={
+        200: {"description": "Jail stopped", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def stop_jail(
     _auth: AuthDep,
@@ -216,6 +246,13 @@ async def stop_jail(
     "/{name}/idle",
     response_model=JailCommandResponse,
     summary="Toggle idle mode for a jail",
+    responses={
+        200: {"description": "Idle mode toggled", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def toggle_idle(
     _auth: AuthDep,
@@ -253,6 +290,13 @@ async def toggle_idle(
     "/{name}/reload",
     response_model=JailCommandResponse,
     summary="Reload a single jail",
+    responses={
+        200: {"description": "Jail reloaded", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def reload_jail(
     _auth: AuthDep,
@@ -294,6 +338,12 @@ class _IgnoreSelfRequest(IgnoreIpRequest):
     "/{name}/ignoreip",
     response_model=IgnoreListResponse,
     summary="List the ignore IPs for a jail",
+    responses={
+        200: {"description": "Ignore list returned", "model": IgnoreListResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def get_ignore_list(
     _auth: AuthDep,
@@ -322,6 +372,14 @@ async def get_ignore_list(
     status_code=status.HTTP_201_CREATED,
     response_model=JailCommandResponse,
     summary="Add an IP or network to the ignore list",
+    responses={
+        201: {"description": "IP added to ignore list", "model": JailCommandResponse},
+        400: {"description": "IP or network invalid"},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def add_ignore_ip(
     _auth: AuthDep,
@@ -359,6 +417,13 @@ async def add_ignore_ip(
     "/{name}/ignoreip",
     response_model=JailCommandResponse,
     summary="Remove an IP or network from the ignore list",
+    responses={
+        200: {"description": "IP removed from ignore list", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def del_ignore_ip(
     _auth: AuthDep,
@@ -392,6 +457,13 @@ async def del_ignore_ip(
     "/{name}/ignoreself",
     response_model=JailCommandResponse,
     summary="Toggle the ignoreself option for a jail",
+    responses={
+        200: {"description": "ignoreself toggled", "model": JailCommandResponse},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        409: {"description": "fail2ban reports operation failed"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def toggle_ignore_self(
     _auth: AuthDep,
@@ -434,6 +506,13 @@ async def toggle_ignore_self(
     "/{name}/banned",
     response_model=JailBannedIpsResponse,
     summary="Return paginated currently-banned IPs for a single jail",
+    responses={
+        200: {"description": "Banned IPs returned", "model": JailBannedIpsResponse},
+        400: {"description": "page or page_size out of range"},
+        401: {"description": "Session missing, expired, or invalid"},
+        404: {"description": "Jail not found"},
+        502: {"description": "fail2ban unreachable"},
+    },
 )
 async def get_jail_banned_ips(
     _auth: AuthDep,