Support automatic documentation for HTMLResponse and RedirectResponse from return type annotations #14172

AlberLC · 2025-10-11T01:06:57Z

AlberLC
Oct 11, 2025

First Check

I added a very descriptive title here.
I used the GitHub search to find a similar question and didn't find it.
I searched the FastAPI documentation, with the integrated search.
I already searched in Google "How to X in FastAPI" and didn't find any information.
I already read and followed all the tutorial in the docs and didn't find an answer.
I already checked if it is not related to FastAPI but to Pydantic.
I already checked if it is not related to FastAPI but to Swagger UI.
I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

I commit to help with one of those options 👆

Example Code

import uvicorn
from fastapi import FastAPI
from fastapi.responses import HTMLResponse

app = FastAPI()


@app.get('/')
async def read_root() -> HTMLResponse:
    html_content = '''
    <html>
        <head><title>Test</title></head>
        <body><h1>Hello, FastAPI!</h1></body>
    </html>
    '''
    return HTMLResponse(content=html_content)


if __name__ == '__main__':
    uvicorn.run('main:app')

Description

Hi!

First of all, I want to say I really love FastAPI and the incredible amount of work it saves when building APIs. I'm also a strong believer in leveraging the language's own features whenever possible, like using Python's return type annotations instead of always relying on response_model or response_class.

One thing that has been bothering me is an possible inconsistency I've noticed: when I use a Pydantic model as a return type annotation, FastAPI automatically generates documentation with the correct schema, status code, and content type. However, when I annotate a function to return HTMLResponse or RedirectResponse, the automatic documentation does not pick up the MIME type or the status code, and I am forced to specify response_class or responses manually.

Since my methods always have return type annotations, it feels natural and cleaner to rely on them for documentation whenever possible. It would be great if FastAPI could support automatic OpenAPI documentation for Response subclasses directly from the return type annotation, just like it does for Pydantic models. Or maybe I’m missing something or lacking experience here 🤔. I’d love to be convinced that the current approach is the right way.

Thanks for your insights!

Operating System

Windows

Operating System Details

No response

FastAPI Version

0.115.12

Pydantic Version

2.11.3

Python Version

Python 3.13.3

Additional Context

No response

luzzodev · 2025-10-11T15:24:05Z

luzzodev
Oct 11, 2025
Collaborator

Hello @AlberLC,
I get your point, but I think the difference between response model and response class is getting mixed up.

Response model

Describes the shape of the response body: fields and schema.
Used for JSON/structured output, validation, etc. (built on Pydantic).
For plain text or HTML responses it’s often unnecessary, but in some cases it’s still crucial.
It’s about the data that will go into the response, not the transport.

Response class

Controls the status code, headers, content type, and encoding.
It takes the data and renders it in the chosen format.

Typical flow
raw_data -> response model -> response class

In FastAPI, a function’s return type (also used for docs) fills the response model, not the response class.
The docs generator uses both the response model and the response class.

By default FastAPI uses JSONResponse as the response class, which is why you’re seeing the wrong MIME type.
You can change the default on the app or a router:

app = FastAPI(default_response_class=HTMLResponse)

Hope this clarifies it!

0 replies

AlberLC · 2025-10-12T16:13:14Z

AlberLC
Oct 12, 2025
Author

Thanks for your reply. I totally understand what you’re saying, everything you explained is true: there’s a clear difference between response_model and response_class, and the return type annotation is currently only used for the model.

However, in my opinion, that doesn’t mean it couldn’t be leveraged to make things more powerful and consistent. Just look at how clean and intuitive the code looks, it feels natural and in line with the elegance FastAPI already provides.

I’m not sure how difficult it would be to implement having the response type information derived from the same place as the model (the return type annotations), but I think it would be a really nice addition.

1 reply

luzzodev Oct 14, 2025
Collaborator

Hey @AlberLC, totally get the appeal of pushing everything into type hints. That said, using the return annotation for both the body and the HTTP response doesn’t feel natural to me.

The return type is great for describing what we return (the body/schema) and for validation/OpenAPI.
Sometimes you still set the response model on the decorator for type-checker needs while preserving the validation step.
When you return an explicit Response, FastAPI skips model validation/serialization and sends it as-is. Mixing body typing with transport would make that even easier to miss.

Blending the “what” (body) with the “how” (media type, status, headers, streaming) adds ambiguity and edge cases, especially once you have multiple outcomes.
There are already plenty of ways to stay concise (sub-apps, routers, sensible defaults), so you can set the transport once and keep return annotations focused on the body.

I’d keep it simple and honest: use the return type for the body, and declare transport explicitly when needed.

AlberLC · 2026-03-02T10:28:04Z

AlberLC
Mar 2, 2026
Author

Hi again,

I’ve revisited this topic over the past months and spent time analyzing FastAPI’s internal routing and OpenAPI generation logic more carefully.

My initial goal was to explore whether return type annotations could be leveraged more consistently, similar to how Pydantic models are handled, but without affecting runtime behavior or introducing fragile heuristics.

After reviewing related discussions and implementation details (including the new JSONL streaming and SSE support), I implemented a prototype that:

Extracts Response subclasses from return annotations.
Uses them exclusively for OpenAPI documentation.
Preserves the existing runtime behavior of response_class.
Maintains compatibility with JSONL streaming and SSE.
Resolves historical issues around unions of Response subclasses.

The change does not alter response rendering logic and preserves existing runtime semantics, while expanding support for unions of Response subclasses.

I’ve opened a PR with full implementation details and comprehensive test coverage: #15040

I’d really appreciate feedback.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support automatic documentation for HTMLResponse and RedirectResponse from return type annotations #14172

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 3 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Support automatic documentation for HTMLResponse and RedirectResponse from return type annotations #14172

Uh oh!

Uh oh!

AlberLC Oct 11, 2025

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

FastAPI Version

Pydantic Version

Python Version

Additional Context

Replies: 3 comments · 1 reply

Uh oh!

luzzodev Oct 11, 2025 Collaborator

Uh oh!

Uh oh!

AlberLC Oct 12, 2025 Author

Uh oh!

luzzodev Oct 14, 2025 Collaborator

Uh oh!

AlberLC Mar 2, 2026 Author

AlberLC
Oct 11, 2025

Replies: 3 comments 1 reply

luzzodev
Oct 11, 2025
Collaborator

AlberLC
Oct 12, 2025
Author

luzzodev Oct 14, 2025
Collaborator

AlberLC
Mar 2, 2026
Author