How to specify the response format using response_class for a specific route?

[Thytu]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue 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

from fastapi import FastAPI, File, UploadFile
from fastapi.responses import FileResponse, Response


app = FastAPI()


class ImageResponse(Response):
    media_type = "image/*"

    # What do I need to add here to specify that 'format = "binary"'


# here I would like to no longer have to specify 'responses' but only use 'response_class' as a single source of information
@app.post("what_I_currently_do",
    response_class=ImageResponse,
    responses={200: {"content": {
        "image/*": {
            "schema":{
                "type":"string",
                "format": "binary"
            }
        }
    }}},
)
async def send_g(b: UploadFile = File(...)):
    return "/tmp/test/b.jpg"

Description

I created a POST route that return a a binary formatted image and I would like this to be specified in the openapi.json endpoint.

For that I currently do it by adding the responses param in the decoder (see "Example code") but I wonder if I can directly specify that the format is binary in the response_class.

Is it possible? If so, how?

Operating System

Linux

Operating System Details

No response

FastAPI Version

0.66.1

Python Version

3.9.7

Additional Context

No response

[ferulisses]

You can try StreamingResponse:
https://fastapi.tiangolo.com/advanced/custom-response/#using-streamingresponse-with-file-like-objects

[JarroVGIT]

The response_class parameter defines how your response is formatted and returned to the caller. The responses parameter allows you to define some documentation on specific return codes. All these return codes might (or might not, incase of validation errors for example) use your response_class to format the end result.

They seem related but they aren't really. To demonstrate how the params response_class and responses effect the documentation:

import typing
from fastapi import BackgroundTasks, FastAPI, File, UploadFile
from fastapi.responses import FileResponse, Response, JSONResponse
from starlette.background import BackgroundTask
import uvicorn

app = FastAPI()

@app.get("/with_direct_jsonresponse")
async def with_direct_jsonresponse():
    return JSONResponse(content="{'hello':'world']", status_code=408) 
    # 408 will not be documented! Will only show a 200 as per default response class

@app.get("with_direct_jsonresponse_and_responses", 
    responses={406:{"description":"in-line 406 response wut?"}})
async def with_direct_jsonresponse_and_responses():
    return JSONResponse(content="{'hello':'world']") 
    # This would document both 200 (as per default response class) and 406

class CustomJSONResponseWith407(JSONResponse):
    media_type = "application/json"
    def __init__(
        self,
        content: typing.Any,
        status_code: int = 407,
        headers: typing.Optional[dict] = None,
        media_type: typing.Optional[str] = None,
        background: typing.Optional[BackgroundTask] = None,
    ) -> None:
        super().__init__(content, status_code, headers, media_type, background)

@app.get("/with_response_class", response_class=CustomJSONResponseWith407) 
async def with_response_class():
    return {"is this": "a 407?"}
    # documents only a 407, as the response class is set to that.

@app.get("/with_response_class_and_responses", 
    response_class=CustomJSONResponseWith407, 
    responses={406:{"description":"in-line 406 response wut?"}}) 
async def with_response_class():
    return {"is this": "a 407?"}
    # documents only a 407 as the response class is set to that,
    # But also a 406.


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000, )    

So, there is no object in the response_class that is used in the documentation as you want it to. Hope this clarifies :)

[JarroVGIT]

You can try StreamingResponse:
https://fastapi.tiangolo.com/advanced/custom-response/#using-streamingresponse-with-file-like-objects

This wouldn't work. See example below:

@app.get("/with_response_class_as_streamingresponse", response_class=StreamingResponse) 
async def with_response_class_as_streamingresponse():
    return {"is this": "a 40x?"}

Results in the following doc:

This is because StreamingResponse as a response_class just let's the documentation know that the default response HTTP code is 200 but basically nothing much else. It even defaults the response content-type to None (didn't expect that actually, interesting behaviour).

[Thytu]

Thank you all for your feedbacks. It sound strange to me to not be able to specify the schema's type within the response_class as it's where we can declare the media_type.

As a workaround I will specify it in the response_class and use it to generate the responses value :

class ImageResponse(Response):
    media_type = "image/*"
    schema = {"something": "another thing"}

@app.post("my_route",
    response_class=ImageResponse,
    responses={200: {"content": {
        "image/*": {
            "schema": ImageResponse.schema
        }
    }}},
)
async def send_g(b: UploadFile = File(...)):
    return "/tmp/test/b.jpg"

it's not perfect but it works 🙂 Don't hesitate if you have any suggestion on how to write that in a better way.

In the mean time I think we can close this issue.