From 4f95407a1bfdc0d63b5c4e78c95f63ef4a92a00e Mon Sep 17 00:00:00 2001 From: moe-berri Date: Thu, 5 Nov 2026 12:19:21 +0800 Subject: [PATCH] fix(api): document and validate created alert rules --- litellm/proxy/_types.py | 4 ++-- .../proxy/alerting_endpoints/usage_alerts.py | 1 + litellm/types/proxy/usage_alerts.py | 6 +++++- scripts/check_openapi_docs.py | 5 +++-- scripts/openapi_docs_gate.py | 4 ++-- tests/unit/test_check_openapi_docs.py | 17 +++++++++++++++++ ui/litellm-dashboard/src/lib/http/schema.d.ts | 5 ++++- 7 files changed, 34 insertions(+), 8 deletions(-) diff --git a/litellm/proxy/_types.py b/litellm/proxy/_types.py index de12eb00c6f..796e334f3cc 100644 --- a/litellm/proxy/_types.py +++ b/litellm/proxy/_types.py @@ -863,12 +863,12 @@ class LiteLLMRoutes(enum.Enum): ] ) - usage_alert_routes = [ + usage_alert_routes = ( "/usage/alert-rules", "/usage/alert-rules/{rule_id}", "/usage/alerts", "/usage/alerts/{alert_id}", - ] + ) self_managed_routes = [ *usage_alert_routes, diff --git a/litellm/proxy/alerting_endpoints/usage_alerts.py b/litellm/proxy/alerting_endpoints/usage_alerts.py index 92ff63072dc..64f06fa62ed 100644 --- a/litellm/proxy/alerting_endpoints/usage_alerts.py +++ b/litellm/proxy/alerting_endpoints/usage_alerts.py @@ -101,6 +101,7 @@ async def list_usage_alert_rules( @router.post("/alert-rules", response_model=UsageAlertRule, status_code=201) async def create_usage_alert_rule(data: UsageAlertRuleInput, user: User, repository: Repository) -> UsageAlertRule: + """Create a daily usage alert rule for a scope the caller can manage.""" store: Final = require_repository(repository) await require_scope(user, store, data.scope_type, data.scope_id, write=True) saved: Final = await store.save_rule(data, user.user_id) diff --git a/litellm/types/proxy/usage_alerts.py b/litellm/types/proxy/usage_alerts.py index 0654fc3022b..070586fef5b 100644 --- a/litellm/types/proxy/usage_alerts.py +++ b/litellm/types/proxy/usage_alerts.py @@ -36,7 +36,11 @@ class UsageAlertRuleInput(BaseModel): raise ValueError("min_history_days must not exceed baseline_days") if self.scope_type == "deployment" and self.scope_id is not None: raise ValueError("Deployment alerts cover the whole gateway; omit scope_id") - if self.scope_type == "key" and self.scope_id is not None and self.scope_id.removeprefix("raw:").startswith("sk-"): + if ( + self.scope_type == "key" + and self.scope_id is not None + and self.scope_id.removeprefix("raw:").startswith("sk-") + ): raise ValueError("Use the key's reporting ID, never the secret key") if len(set(self.notification_channels)) != len(self.notification_channels): raise ValueError("notification_channels must be unique") diff --git a/scripts/check_openapi_docs.py b/scripts/check_openapi_docs.py index 219ef912952..c6c7224e35d 100755 --- a/scripts/check_openapi_docs.py +++ b/scripts/check_openapi_docs.py @@ -7,7 +7,7 @@ count them per rule the same delta-vs-base way as the other lint gates. The rule OA001 no request body schema (the handler reads ``request.body()`` and never told FastAPI what is in it, see ``inline_request_body`` in custom_openapi_spec.py for the fix) OA002 no description (the handler has no docstring and the route no ``description=``) -OA003 the 200 response has no schema (no ``response_model`` and no ``responses={200: ...}``) +OA003 the 200 or 201 response has no schema (no ``response_model`` or explicit response schema) """ from __future__ import annotations @@ -45,7 +45,8 @@ def _operation_codes(operation: Mapping[str, object]) -> Iterator[str]: description: Final = operation.get("description") if not isinstance(description, str) or not description.strip(): yield "OA002" - if not _content_schema(_as_mapping(operation.get("responses")).get("200")): + responses: Final = _as_mapping(operation.get("responses")) + if not _content_schema(responses.get("200", responses.get("201"))): yield "OA003" diff --git a/scripts/openapi_docs_gate.py b/scripts/openapi_docs_gate.py index de340bf84e7..7b4a7e19e57 100755 --- a/scripts/openapi_docs_gate.py +++ b/scripts/openapi_docs_gate.py @@ -5,7 +5,7 @@ Sibling of scripts/test_quality_gate.py, pointed at the proxy's OpenAPI document instead of a source tree. Each rule is counted over every POST operation the proxy serves at HEAD and at the merge-base with the branch this change merges into, and the gate fails only when a rule grew past the merge-base count, so a new endpoint has to -ship with a request schema, a description and a 200 schema while the undocumented +ship with a request schema, a description and a 200/201 schema while the undocumented routes that already exist are only ever allowed to shrink. The merge-base counts come from scripts/lint_base_counts.py: the disk cache, then the @@ -167,7 +167,7 @@ def cmd_check(base: str) -> None: print( "Give every new POST route a request body schema (a typed body parameter, or " "`openapi_extra={'requestBody': inline_request_body(Model, example)}` when the handler reads " - "`request.body()`), a docstring, and a 200 schema (`response_model=` or `responses={200: {'model': ...}}`), " + "`request.body()`), a docstring, and a 200/201 schema (`response_model=` or an explicit response schema), " "or document an equal number of existing routes; the ceiling is the merge-base count. Run " "`python scripts/check_openapi_docs.py` to see every finding." ) diff --git a/tests/unit/test_check_openapi_docs.py b/tests/unit/test_check_openapi_docs.py index c6ea0cd936e..7d5f09c522b 100644 --- a/tests/unit/test_check_openapi_docs.py +++ b/tests/unit/test_check_openapi_docs.py @@ -40,6 +40,23 @@ def test_each_missing_piece_is_its_own_rule() -> None: assert codes == {"OA001", "OA002", "OA003"} +def test_created_response_schema_satisfies_the_success_contract() -> None: + operation: Final = {**_DOCUMENTED, "responses": {"201": _RESPONSES["200"]}} + assert checker.violations({"paths": {"/v1/thing": {"post": operation}}}) == () + + +@pytest.mark.parametrize("responses", [ + {"201": {"description": "Created"}}, + {"400": _RESPONSES["200"]}, + {"200": {}, "201": _RESPONSES["200"]}, +]) +def test_success_response_must_still_have_a_schema(responses: Mapping[str, object]) -> None: + operation: Final = {**_DOCUMENTED, "responses": responses} + assert checker.violations({"paths": {"/v1/thing": {"post": operation}}}) == ( + checker.Violation("POST", "/v1/thing", "OA003"), + ) + + @pytest.mark.parametrize("body", [{}, {"content": {"multipart/form-data": {}}}]) def test_only_the_missing_piece_is_reported(body: Mapping[str, object]) -> None: no_body: Final = {**_DOCUMENTED, "requestBody": body} diff --git a/ui/litellm-dashboard/src/lib/http/schema.d.ts b/ui/litellm-dashboard/src/lib/http/schema.d.ts index 98f7c623c20..cd55938d7c3 100644 --- a/ui/litellm-dashboard/src/lib/http/schema.d.ts +++ b/ui/litellm-dashboard/src/lib/http/schema.d.ts @@ -18844,7 +18844,10 @@ export interface paths { /** List Usage Alert Rules */ get: operations["list_usage_alert_rules_usage_alert_rules_get"]; put?: never; - /** Create Usage Alert Rule */ + /** + * Create Usage Alert Rule + * @description Create a daily usage alert rule for a scope the caller can manage. + */ post: operations["create_usage_alert_rule_usage_alert_rules_post"]; delete?: never; options?: never;