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

@@ -128,6 +128,11 @@ _NamePath = Annotated[
"",
response_model=ActionListResponse,
summary="List all available actions with active/inactive status",
responses={
200: {"description": "Action list returned", "model": ActionListResponse},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def list_actions(
request: Request,
@@ -165,6 +170,12 @@ async def list_actions(
"/{name}",
response_model=ActionConfig,
summary="Return full parsed detail for a single action",
responses={
200: {"description": "Action config returned", "model": ActionConfig},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "Action not found in action.d/"},
502: {"description": "fail2ban unreachable"},
},
)
async def get_action(
request: Request,
@@ -205,6 +216,14 @@ async def get_action(
response_model=ActionConfig,
summary="Update an action's .local override with new lifecycle command values",
dependencies=[Depends(_check_action_update_rate_limit)],
responses={
200: {"description": "Action updated", "model": ActionConfig},
400: {"description": "Invalid action name"},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "Action not found"},
429: {"description": "Rate limit exceeded for action update operations"},
500: {"description": "Failed to write .local file"},
},
)
async def update_action(
request: Request,
@@ -246,6 +265,14 @@ async def update_action(
status_code=status.HTTP_201_CREATED,
summary="Create a new user-defined action",
dependencies=[Depends(_check_action_create_rate_limit)],
responses={
201: {"description": "Action created", "model": ActionConfig},
400: {"description": "Invalid action name"},
401: {"description": "Session missing, expired, or invalid"},
409: {"description": "Action already exists"},
429: {"description": "Rate limit exceeded for action create operations"},
500: {"description": "Failed to write .local file"},
},
)
async def create_action(
request: Request,
@@ -284,6 +311,15 @@ async def create_action(
status_code=status.HTTP_204_NO_CONTENT,
summary="Delete a user-created action's .local file",
dependencies=[Depends(_check_action_delete_rate_limit)],
responses={
204: {"description": "Action deleted successfully"},
400: {"description": "Invalid action name"},
401: {"description": "Session missing, expired, or invalid"},
404: {"description": "Action not found"},
409: {"description": "Action is a shipped default (conf-only)"},
429: {"description": "Rate limit exceeded for action delete operations"},
500: {"description": "Failed to delete .local file"},
},
)
async def delete_action(
request: Request,