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:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user