lukas.pupkalipinski/BanGUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Lukas
2026-05-03 01:12:08 +02:00
parent 7ad885d276
commit 8f26776bb3
15 changed files with 624 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
backend/app/routers/bans.py
View File

@@ -101,6 +101,11 @@ def _check_unban_rate_limit(
"/active",
response_model=ActiveBanListResponse,
summary="List all currently banned IPs across all jails",
responses={
200: {"description": "Active ban list returned", "model": ActiveBanListResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_active_bans(
request: Request,
@@ -144,6 +149,15 @@ async def get_active_bans(
response_model=JailCommandResponse,
summary="Ban an IP address in a specific jail",
dependencies=[Depends(_check_ban_rate_limit)],
responses={
201: {"description": "IP banned successfully", "model": JailCommandResponse},
400: {"description": "Invalid IP address"},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "Jail not found"},
409: {"description": "Ban command failed in fail2ban"},
429: {"description": "Rate limit exceeded for ban operations"},
502: {"description": "fail2ban unreachable"},
},
)
async def ban_ip(
request: Request,
@@ -182,6 +196,15 @@ async def ban_ip(
response_model=JailCommandResponse,
summary="Unban an IP address from one or all jails",
dependencies=[Depends(_check_unban_rate_limit)],
responses={
200: {"description": "IP unbanned successfully", "model": JailCommandResponse},
400: {"description": "Invalid IP address"},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "Jail not found"},
409: {"description": "Unban command failed in fail2ban"},
429: {"description": "Rate limit exceeded for unban operations"},
502: {"description": "fail2ban unreachable"},
},
)
async def unban_ip(
request: Request,
@@ -225,6 +248,11 @@ async def unban_ip(
"/all",
response_model=UnbanAllResponse,
summary="Unban every currently banned IP across all jails",
responses={
200: {"description": "All bans cleared", "model": UnbanAllResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def unban_all(
request: Request,