From 3d67642b99676ed7e389a75083876b38e92e04ab Mon Sep 17 00:00:00 2001 From: champ-sk Date: Mon, 5 Jan 2026 18:29:26 +0530 Subject: [PATCH] Docs: clarify runtime vs OpenAPI behavior of responses model --- docs/en/docs/advanced/additional-responses.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/en/docs/advanced/additional-responses.md b/docs/en/docs/advanced/additional-responses.md index bb70753edd..43959d3038 100644 --- a/docs/en/docs/advanced/additional-responses.md +++ b/docs/en/docs/advanced/additional-responses.md @@ -22,6 +22,16 @@ It receives a `dict`: the keys are status codes for each response (like `200`), Each of those response `dict`s can have a key `model`, containing a Pydantic model, just like `response_model`. +/// note +The `model` key inside `responses` is used **only for OpenAPI +documentation generation**. + +It does **not** perform runtime response validation or filtering. + +If you want FastAPI to validate and filter the returned data at +runtime, use `response_model` instead. +/// + **FastAPI** will take that model, generate its JSON Schema and include it in the correct place in OpenAPI. For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write: