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,12 @@ _IpPath = Annotated[str, Path(description="IPv4 or IPv6 address to look up.")]
"/lookup/{ip}",
response_model=IpLookupResponse,
summary="Look up ban status and geo information for an IP",
responses={
200: {"description": "IP lookup result returned", "model": IpLookupResponse},
400: {"description": "Invalid IP address"},
401: {"description": "Session missing, expired, or invalid"},
502: {"description": "fail2ban unreachable"},
},
)
async def lookup_ip(
_auth: AuthDep,
@@ -75,6 +81,10 @@ async def lookup_ip(
"/stats",
response_model=GeoCacheStatsResponse,
summary="Geo cache diagnostic counters",
responses={
200: {"description": "Geo cache stats returned", "model": GeoCacheStatsResponse},
401: {"description": "Session missing, expired, or invalid"},
},
)
async def geo_stats(
_auth: AuthDep,
@@ -99,6 +109,10 @@ async def geo_stats(
"/re-resolve",
summary="Re-resolve all IPs whose country could not be determined",
response_model=GeoReResolveResponse,
responses={
200: {"description": "Re-resolve result", "model": GeoReResolveResponse},
401: {"description": "Session missing, expired, or invalid"},
},
)
async def re_resolve_geo(
_auth: AuthDep,