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

@@ -30,6 +30,11 @@ router: APIRouter = APIRouter(prefix="/api/v1/server", tags=["Server"])
"/settings",
response_model=ServerSettingsResponse,
summary="Return fail2ban server-level settings",
responses={
200: {"description": "Server settings returned", "model": ServerSettingsResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_server_settings(
request: Request,
@@ -59,6 +64,12 @@ async def get_server_settings(
"/settings",
status_code=status.HTTP_204_NO_CONTENT,
summary="Update fail2ban server-level settings",
responses={
204: {"description": "Settings updated successfully"},
400: {"description": "Set command rejected by fail2ban"},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def update_server_settings(
request: Request,
@@ -88,6 +99,12 @@ async def update_server_settings(
status_code=status.HTTP_200_OK,
summary="Flush and re-open fail2ban log files",
response_model=FlushLogsResponse,
responses={
200: {"description": "Logs flushed successfully", "model": FlushLogsResponse},
400: {"description": "Command rejected by fail2ban"},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def flush_logs(
request: Request,