✨ Generate correct OpenAPI docs for responses with no content (#621)

docs/tutorial/additional-responses.md

@@ -174,6 +174,11 @@ For example, you can add an additional media type of `image/png`, declaring that
 !!! note
     Notice that you have to return the image using a `FileResponse` directly.
 
+!!! info
+    Unless you specify a different media type explicitly in your `responses` parameter, FastAPI will assume the response has the same media type as the main response class (default `application/json`).
+
+    But if you have specified a custom response class with `None` as its media type, FastAPI will use `application/json` for any additional response that has an associated model.
+
 ## Combining information
 
 You can also combine response information from multiple places, including the `response_model`, `status_code`, and `responses` parameters.

docs/tutorial/custom-response.md

@@ -15,6 +15,9 @@ The contents that you return from your *path operation function* will be put ins
 
 And if that `Response` has a JSON media type (`application/json`), like is the case with the `JSONResponse` and `UJSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*.
 
+!!! note
+    If you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.
+
 ## Use `UJSONResponse`
 
 For example, if you are squeezing performance, you can install and use `ujson` and set the response to be Starlette's `UJSONResponse`.

docs/tutorial/response-status-code.md

@@ -22,6 +22,10 @@ It will:
 
 <img src="/img/tutorial/response-status-code/image01.png">
 
+!!! note
+    Some response codes (see the next section) indicate that the response does not have a body.
+
+    FastAPI knows this, and will produce OpenAPI docs that state there is no response body.
 
 ## About HTTP status codes
 
@@ -34,11 +38,12 @@ These status codes have a name associated to recognize them, but the important p
 
 In short:
 
-* `100` and above are for "Information". You rarely use them directly.
+* `100` and above are for "Information". You rarely use them directly.  Responses with these status codes cannot have a body.
 * **`200`** and above are for "Successful" responses. These are the ones you would use the most.
     * `200` is the default status code, which means everything was "OK".
     * Another example would be `201`, "Created". It is commonly used after creating a new record in the database.
-* `300` and above are for "Redirection". 
+    * A special case is `204`, "No Content".  This response is used when there is no content to return to the client, and so the response must not have a body.
+* **`300`** and above are for "Redirection".  Responses with these status codes may or may not have a body, except for `304`, "Not Modified", which must not have one.
 * **`400`** and above are for "Client error" responses. These are the second type you would probably use the most.
     * An example is `404`, for a "Not Found" response.
     * For generic errors from the client, you can just use `400`.