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>
This commit is contained in:
2026-05-03 01:12:08 +02:00
parent 7ad885d276
commit 8f26776bb3
15 changed files with 624 additions and 2 deletions

View File

@@ -41,6 +41,11 @@ router: APIRouter = APIRouter(prefix="/api/v1/history", tags=["History"])
"",
response_model=HistoryListResponse,
summary="Return a paginated list of historical bans",
responses={
200: {"description": "History list returned", "model": HistoryListResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_history(
request: Request,
@@ -120,6 +125,11 @@ async def get_history(
"/archive",
response_model=HistoryListResponse,
summary="Return a paginated list of archived historical bans",
responses={
200: {"description": "Archived history list returned", "model": HistoryListResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_history_archive(
request: Request,
@@ -157,6 +167,12 @@ async def get_history_archive(
"/{ip}",
response_model=IpDetailResponse,
summary="Return the full ban history for a single IP address",
responses={
200: {"description": "IP history detail returned", "model": IpDetailResponse},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "No history found for this IP"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_ip_history(
request: Request,