Document operational responses in OpenAPI

Author: kennethreitz

CHANGELOG.md

@@ -40,6 +40,12 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - `max_request_size` now defaults to 100 MiB instead of unlimited; pass
   `API(max_request_size=None)` for the previous behavior. Oversized bodies
   get a `413` as before.
+- Generated OpenAPI operations now document Responder's operational responses:
+  CSRF-protected unsafe routes get `403`, rate-limited routes get `429` (and
+  fail-closed backend `503`), and request-size `413` is emitted only when a
+  body cap is active. Rate limiter `429`/`503` responses now honor
+  `API(problem_details=True)` and keep the legacy `{"error": ...}` JSON shape
+  when `problem_details=False`.
 - Because multipart parsing streams, the raw body is consumed by the parse:
   `await req.content` after `media("form"/"files")` raises a clear
   `RuntimeError` (await `req.content` first to keep the buffered, replayable

docs/source/tour.rst

@@ -859,6 +859,12 @@ endpoints are excluded for you::
     def internal(req, resp):
         resp.text = "private"
 
+Operational responses are documented too. CSRF-protected unsafe routes show
+``403``, capped request bodies show ``413``, rate-limited routes show
+``429`` (and fail-closed backend ``503``), and configured request timeouts
+show ``504``. With the default Problem Details contract, those responses
+reference the reusable ``ProblemDetails`` schema.
+
 Beyond that baseline, three tools let you enrich and override the generated
 operations.
 
@@ -1419,6 +1425,10 @@ When the limit is exceeded, clients receive a ``429 Too Many Requests``
 response with a ``Retry-After`` header. Every response includes
 ``X-RateLimit-Limit``, ``X-RateLimit-Remaining``, and ``X-RateLimit-Reset``
 (seconds until the window resets) headers so clients can pace themselves.
+With the default ``problem_details=True`` setting, over-limit and fail-closed
+backend responses use the same ``application/problem+json`` envelope as
+framework-generated errors; pass ``problem_details=False`` on the API to keep
+the legacy ``{"error": ...}`` JSON body.
 
 The rate limiter is per-client, keyed by IP address by default. To key by
 something else — an API key, an authenticated user id — pass ``key=``, a

responder/ext/openapi/__init__.py

@@ -25,10 +25,10 @@
     "400": "Bad Request",
     "404": "Not Found",
     "405": "Method Not Allowed",
-    "413": "Content Too Large",
     "500": "Internal Server Error",
 }
 _AUTH_INJECTION_NAMES = frozenset({"auth", "principal", "user"})
+_CSRF_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "TRACE"})
 
 
 def _problem_details_schema() -> dict:
@@ -560,21 +560,47 @@ def _apply_problem_responses(
     *,
     has_validation: bool,
     secured: bool,
+    csrf_protected: bool,
+    body_limited: bool,
+    rate_limited: bool,
     timed: bool,
     problem_details: bool,
 ) -> None:
     response = _problem_response if problem_details else _legacy_error_response
     for status, description in _COMMON_PROBLEM_STATUSES.items():
         op["responses"].setdefault(status, response(description))
+    if body_limited:
+        op["responses"].setdefault("413", response("Content Too Large"))
     if has_validation:
         op["responses"]["422"] = response("Validation Error", validation=True)
     if secured:
         op["responses"].setdefault("401", response("Not Authenticated"))
         op["responses"].setdefault("403", response("Forbidden"))
+    elif csrf_protected:
+        op["responses"].setdefault("403", response("Forbidden"))
+    if rate_limited:
+        op["responses"].setdefault("429", response("Too Many Requests"))
+        op["responses"].setdefault("503", response("Service Unavailable"))
     if timed:
         op["responses"].setdefault("504", response("Gateway Timeout"))
 
 
+def _csrf_protected(app: Any, endpoint: Any, op_endpoint: Any, method: str) -> bool:
+    if method.upper() in _CSRF_SAFE_METHODS:
+        return False
+    route_csrf = _operation_attr(endpoint, op_endpoint, "_csrf")
+    if route_csrf is None:
+        return bool(getattr(getattr(app, "router", None), "csrf", False))
+    return bool(route_csrf)
+
+
+def _rate_limited(app: Any, endpoint: Any, op_endpoint: Any) -> bool:
+    return bool(
+        getattr(app, "_openapi_rate_limited", False)
+        or _operation_attr(endpoint, op_endpoint, "_rate_limited", False)
+    )
+
+
 def _doc_methods(route: Any, has_body: bool = False) -> list[str]:
     """Lowercased HTTP methods to document for a route (no HEAD/OPTIONS)."""
     methods = getattr(route, "methods", None)
@@ -867,6 +893,9 @@ def _spec_cache_key(self):
             getattr(router, "_generation", None),
             len(getattr(router, "routes", ()) or ()),
             len(getattr(router, "dependencies", {}) or {}),
+            getattr(router, "max_request_size", None),
+            getattr(router, "csrf", False),
+            getattr(self.app, "_openapi_rate_limited", False),
             len(self.schemas),
             len(self.pydantic_schemas),
             len(self.security_schemes),
@@ -1100,6 +1129,14 @@ def remember_model(model):
                     op,
                     has_validation=has_body or has_param_validation,
                     secured=secured,
+                    csrf_protected=_csrf_protected(
+                        self.app, endpoint, op_endpoint, method
+                    ),
+                    body_limited=getattr(
+                        self.app.router, "max_request_size", None
+                    )
+                    is not None,
+                    rate_limited=_rate_limited(self.app, endpoint, op_endpoint),
                     timed=getattr(self.app.router, "request_timeout", None) is not None,
                     problem_details=getattr(self.app, "problem_details", True),
                 )

responder/ext/ratelimit.py

@@ -294,14 +294,30 @@ def _apply(self, allowed, remaining, reset_after, resp):
         if reset_after is not None:
             resp.headers["X-RateLimit-Reset"] = str(math.ceil(reset_after))
         if not allowed:
-            resp.status_code = 429
-            resp.media = {"error": "rate limit exceeded"}
-            resp.headers["Retry-After"] = str(self.period)
+            headers = {"Retry-After": str(self.period)}
+            if self._use_problem_details(resp):
+                resp.problem(
+                    429,
+                    "Rate limit exceeded.",
+                    title="Too Many Requests",
+                    headers=headers,
+                )
+            else:
+                resp.status_code = 429
+                resp.media = {"error": "rate limit exceeded"}
+                resp.headers.update(headers)
             return False
         resp.headers["X-RateLimit-Limit"] = str(self.max_requests)
         resp.headers["X-RateLimit-Remaining"] = str(remaining)
         return True
 
+    @staticmethod
+    def _use_problem_details(resp):
+        request = getattr(resp, "req", None)
+        starlette_req = getattr(request, "_starlette", None)
+        scope = getattr(starlette_req, "scope", None)
+        return bool(scope and scope.get("problem_details"))
+
     def _apply_failure(self, exc, resp):
         if self.fail_open:
             logger.warning(
@@ -319,9 +335,18 @@ def _apply_failure(self, exc, resp):
             type(exc).__name__,
             exc,
         )
-        resp.status_code = 503
-        resp.media = {"error": "rate limit backend unavailable"}
-        resp.headers["Retry-After"] = str(self.period)
+        headers = {"Retry-After": str(self.period)}
+        if self._use_problem_details(resp):
+            resp.problem(
+                503,
+                "Rate limit backend unavailable.",
+                title="Service Unavailable",
+                headers=headers,
+            )
+        else:
+            resp.status_code = 503
+            resp.media = {"error": "rate limit backend unavailable"}
+            resp.headers.update(headers)
         return False
 
     def check(self, req, resp):
@@ -380,11 +405,18 @@ def wrapper(req, resp, *args, **kwargs):
                     return f(req, resp, *args, **kwargs)
                 return None
 
+        wrapper._rate_limited = True  # type: ignore[attr-defined]
+        wrapper._rate_limiter = self  # type: ignore[attr-defined]
         return wrapper
 
     def install(self, api):
         """Install as a before_request hook on the API (async, any backend)."""
 
+        api._openapi_rate_limited = True
+        api._openapi_rate_limiter = self
+        if hasattr(api, "openapi"):
+            api.openapi._spec_cache = None
+
         @api.route(before_request=True)
         async def _rate_limit(req, resp):
             await self.acheck(req, resp)

tests/test_openapi_operational_90.py

@@ -0,0 +1,167 @@
+"""v9.0: generated OpenAPI documents framework operational responses."""
+
+import yaml
+from openapi_spec_validator import validate
+from starlette.testclient import TestClient
+
+import responder
+from responder.ext.ratelimit import RateLimiter, RedisBackend
+
+
+def _api(**kwargs):
+    kwargs.setdefault("openapi", "3.1.0")
+    kwargs.setdefault("secret_key", "x" * 32)
+    kwargs.setdefault("allowed_hosts", [";"])
+    kwargs.setdefault("session_https_only", False)
+    return responder.API(**kwargs)
+
+
+def _schema(api):
+    response = TestClient(api, base_url="http://;").get("/schema.yml")
+    assert response.status_code == 200
+    return yaml.safe_load(response.content)
+
+
+def test_openapi_documents_csrf_only_on_protected_unsafe_routes():
+    api = _api(csrf=True)
+
+    @api.get("/form")
+    def form(req, resp):
+        resp.text = str(req.csrf_input)
+
+    @api.post("/submit")
+    def submit(req, resp):
+        resp.media = {"ok": True}
+
+    @api.post("/webhook", csrf=False)
+    def webhook(req, resp):
+        resp.media = {"ok": True}
+
+    spec = _schema(api)
+
+    form_responses = spec["paths"]["/form"]["get"]["responses"]
+    submit_responses = spec["paths"]["/submit"]["post"]["responses"]
+    webhook_responses = spec["paths"]["/webhook"]["post"]["responses"]
+
+    assert "403" not in form_responses
+    assert "403" in submit_responses
+    assert "401" not in submit_responses
+    assert "403" not in webhook_responses
+    assert "application/problem+json" in submit_responses["403"]["content"]
+    validate(spec)
+
+
+def test_openapi_documents_route_level_rate_limits():
+    api = _api()
+    limiter = RateLimiter(requests=1, period=60)
+
+    @api.get("/limited")
+    @limiter.limit
+    def limited(req, resp):
+        resp.media = {"ok": True}
+
+    @api.get("/open")
+    def open_route(req, resp):
+        resp.media = {"ok": True}
+
+    spec = _schema(api)
+    limited_responses = spec["paths"]["/limited"]["get"]["responses"]
+    open_responses = spec["paths"]["/open"]["get"]["responses"]
+
+    assert "429" in limited_responses
+    assert "503" in limited_responses
+    assert "application/problem+json" in limited_responses["429"]["content"]
+    assert "429" not in open_responses
+    assert "503" not in open_responses
+    validate(spec)
+
+
+def test_openapi_documents_installed_rate_limiter_on_all_routes():
+    api = _api()
+    RateLimiter(requests=1, period=60).install(api)
+
+    @api.get("/one")
+    def one(req, resp):
+        resp.media = {"ok": True}
+
+    @api.post("/two")
+    def two(req, resp):
+        resp.media = {"ok": True}
+
+    spec = _schema(api)
+
+    assert "429" in spec["paths"]["/one"]["get"]["responses"]
+    assert "429" in spec["paths"]["/two"]["post"]["responses"]
+    validate(spec)
+
+
+def test_openapi_omits_413_when_request_body_limit_disabled():
+    api = _api(max_request_size=None)
+
+    @api.post("/items")
+    def items(req, resp):
+        resp.media = {"ok": True}
+
+    spec = _schema(api)
+
+    assert "413" not in spec["paths"]["/items"]["post"]["responses"]
+    validate(spec)
+
+
+def test_rate_limiter_uses_problem_details_by_default():
+    api = _api()
+    RateLimiter(requests=1, period=60).install(api)
+
+    @api.get("/")
+    def index(req, resp):
+        resp.text = "ok"
+
+    client = TestClient(api, base_url="http://;")
+    assert client.get("/").status_code == 200
+
+    response = client.get("/")
+
+    assert response.status_code == 429
+    assert response.headers["content-type"].startswith("application/problem+json")
+    assert response.headers["Retry-After"] == "60"
+    assert response.json()["title"] == "Too Many Requests"
+
+
+def test_rate_limiter_keeps_legacy_error_shape_when_problem_details_disabled():
+    api = _api(problem_details=False)
+    RateLimiter(requests=1, period=60).install(api)
+
+    @api.get("/")
+    def index(req, resp):
+        resp.text = "ok"
+
+    client = TestClient(api, base_url="http://;")
+    assert client.get("/").status_code == 200
+
+    response = client.get("/")
+
+    assert response.status_code == 429
+    assert response.headers["content-type"].startswith("application/json")
+    assert response.json() == {"error": "rate limit exceeded"}
+
+
+def test_rate_limiter_backend_failure_uses_problem_details():
+    class DownRedis:
+        def eval(self, *args, **kwargs):
+            raise RuntimeError("down")
+
+    api = _api()
+    RateLimiter(
+        requests=1, period=60, backend=RedisBackend(client=DownRedis())
+    ).install(api)
+
+    @api.get("/")
+    def index(req, resp):
+        resp.text = "never"
+
+    response = TestClient(api, base_url="http://;").get("/")
+
+    assert response.status_code == 503
+    assert response.headers["content-type"].startswith("application/problem+json")
+    assert response.headers["Retry-After"] == "60"
+    assert response.json()["title"] == "Service Unavailable"

tests/test_redis_backends.py

@@ -454,7 +454,9 @@ async def index(req, resp):
     assert r.status_code == 429
     assert r.headers["Retry-After"] == "60"
     assert 0 < int(r.headers["X-RateLimit-Reset"]) <= 60
-    assert r.json() == {"error": "rate limit exceeded"}
+    body = r.json()
+    assert body["title"] == "Too Many Requests"
+    assert body["detail"] == "Rate limit exceeded."
 
 
 def test_redis_ratelimit_connection_error_propagates():
@@ -481,7 +483,9 @@ async def index(req, resp):
     r = api.requests.get("/")
     assert r.status_code == 503
     assert r.headers["Retry-After"] == "60"
-    assert r.json() == {"error": "rate limit backend unavailable"}
+    body = r.json()
+    assert body["title"] == "Service Unavailable"
+    assert body["detail"] == "Rate limit backend unavailable."
 
 
 def test_redis_ratelimit_outage_fail_open_allows_requests():

tests/test_round4.py

@@ -332,7 +332,9 @@ def view(req, resp):
     assert api.requests.get("/r").status_code == 200
     over = api.requests.get("/r")
     assert over.status_code == 429
-    assert over.json() == {"error": "rate limit exceeded"}
+    body = over.json()
+    assert body["title"] == "Too Many Requests"
+    assert body["detail"] == "Rate limit exceeded."
     assert over.headers["Retry-After"] == "60"
     # The handler is not invoked once the limit is exceeded.
     assert calls["n"] == 2