Can the OpenAPI Schema autogenerated from an UploadFile be customised?

[chan-vince]

First check

• [✔️] 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.

Description

Is it possible to customise the documentation generated by fastapi when I define an UploadFile object to a POST method?

Additional context

Say for example I had a method like this where a file can be uploaded:

@router.post("/entity/new",)
async def upload_new_entity(file: UploadFile = File(...):
    return {"filename": file.filename}

This seems to generate an entry in the schemas section of the docs with the pattern of Body<func_name><path><method>

So my example above will have a Schema entry with the name:
Body_upload_new_entity_entity_new_post

The docs for UploadFile don't mention anything about OpenAPI docs.

Is it possible to specify a name for this UploadFile instead? And ideally also customise the details within the schema?

Thanks

[rdhite]

I have a similar issue for a very different use case. I need to use the Request object directly to deal with data as it comes in in realtime, but I have no way to get the autogenerated docs to show what the body should be. Specifically, I need the docs to say the body parameter is raw binary with content-type of application/octet stream, but there's no way to add custom documentation via code. Using File and UploadFile aren't options because clients will not be using forms.

[chan-vince]

I actually switched to using File/UploadFile because I thought I could get closer to it being documented with the autogenerated docs. So now I have the API endpoint documented quite nicely, as it can do multipart/form-data. I'm only missing a better definition of the UploadFile itself.

Originally I started with what you have - the request body be raw bytes (either application/octet-stream or application/cbor) and then the metadata associated with it set with custom headers. Then use the Request object directly. I moved to UploadFile thinking that it would integrate properly with the docs but it's not quite there yet.

I think both scenarios would benefit from being able to manually specify things (other than examples) in the autogenerated docs!

[Grish18]

I have a similar concern as well, my request body was first defined using the Form parameter class because I needed to have a content type of "application/x-www-form-urlencoded". The request body was documented properly as expected but my schema entry followed the Body<func_name> naming convention.

I tried also using Class as Dependencies using the Form parameter and still had the same effect: I got my desired content type but my schema entry name didn't follow my class name. I also tried using a pydantic model using the Form parameter but my content type was switched to "application/json" even if I used Form parameter type or explicitly set the media_type param to "application/x-www-form-urlencoded".

I was hoping I could define form type request bodies using pydantic models similar to json request bodies and get the same naming convention. I'm very new to python and openapi so been trying to read as much as I can. Hope someone can help point me to the right direction! Also want to say thanks for the awesome framework, it's well documented and been a joy to learn and use!

[paolieri]

Using UploadFile, I ran into the same autogenerated Body_method_param_verb schema name in the OpenAPI docs. It would be great to have a way to customize this!

[chan-vince]

Seems like we're in agreement that we'd like to be able to specify how the code leads to generated docs.
Any suggestions for how this could be improved without it cluttering the function decorators for example, or requiring users to be familiar with the OpenAPI spec?

[Grish18]

Maybe we can use Pydantic to model the form data? Would be consistent to how we declare a request body, as demonstrated in the documentation. I thought I had to use a Pydantic model to get the proper name in the documentation, so I tried passing a mode, or declaring a form that depends on a plain python class but still didn't work. Again not so sure this is the best way because this is my first time using python but I thought I would follow the same examples in the documentation.

[tiangolo]

You can add extra JSON Schema/OpenAPI parameters to File(), it's documented here: https://fastapi.tiangolo.com/tutorial/schema-extra-example/#field-additional-arguments

For example:

from fastapi import FastAPI, UploadFile, File

app = FastAPI()


@app.post("/entity/new", operation_id="file")
async def upload_new_entity(
    file: UploadFile = File(
        ..., description="The file with the entity to process"
    )
):
    return {"filename": file.filename}

About the name of the autogenerated schema, the way it is autogenerated is to ensure that it is unique. That's why the long and weird name. Otherwise, you could end up having several JSON schemas with the same name, say UploadFile, so they would overwrite each other.

Unfortunately, there's currently no way to modify the autogenerated name of the body for form/file parameters without modifying the OpenAPI schema. I don't imagine how that could work, as it has to generate a virtual schema live from the possibly multiple form fields. 🤔

But if you want to modify the OpenAPI schema, here are the docs: https://fastapi.tiangolo.com/advanced/extending-openapi/

[synchronizing]

@tiangolo Would it not be possible to have a new schema_name param for every router.get, router.post, etc. wrapper to indicate the new name? Would be a helpful addon, specially for those that are generating client codes via the OpenAPI schema that FastAPI provides.

Frankly, any way to modify the schema name would be helpful.

[synchronizing]

After some investigation this is possible, but it requires some monkey patching. Using the example given here, the solution looks like so:

from fastapi import FastAPI, File, UploadFile
from typing import Callable

app = FastAPI()

@app.post("/files/")
async def create_file(file: bytes = File(...)):
    return {"file_size": len(file)}

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile = File(...)):
    return {"filename": file.filename}

def update_schema_name(app: FastAPI, function: Callable, name: str) -> None:
    """
    Updates the Pydantic schema name for a FastAPI function that takes
    in a fastapi.UploadFile = File(...) or bytes = File(...).

    This is a known issue that was reported on FastAPI#1442 in which
    the schema for file upload routes were auto-generated with no
    customization options. This renames the auto-generated schema to
    something more useful and clear.

    Args:
        app: The FastAPI application to modify.
        function: The function object to modify.
        name: The new name of the schema.
    """
    for route in app.routes:
        if route.endpoint is function:
            route.body_field.type_.__name__ = name
            break

update_schema_name(app, create_file, "CreateFileSchema")
update_schema_name(app, create_upload_file, "CreateUploadSchema")

[adriangb]

Here is a solution to move the schema from the Schemas to the path itself in OpenAPI without touching the routing or anything:

from fastapi import FastAPI, File, UploadFile
from fastapi.openapi.utils import get_openapi


app = FastAPI()


@app.post("/uploadfile/")
async def create_upload_file(file1: UploadFile = File(...), file2: UploadFile = File(...)):
    pass


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        description="This is a very custom OpenAPI schema",
        routes=app.routes,
    )
    # Move autogenerated Body_ schemas, see https://github.com/tiangolo/fastapi/issues/1442
    for path in openapi_schema["paths"].values():
        for method_data in path.values():
            if "requestBody" in method_data:
                for content_type, content in method_data["requestBody"]["content"].items():
                    if content_type == "multipart/form-data":
                        schema_name = content["schema"]["$ref"].lstrip("#/components/schemas/")
                        schema_data = openapi_schema["components"]["schemas"].pop(schema_name)
                        content["schema"] = schema_data
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

In this case, my main goal was to just not list this as a Schema in swagger. But presumably something similar could be done to rename the models (although I don't think it's very helpful to have them in the Schemas section, especially since they're unique to each endpoint/method).

Since modifying/extending the OpenAPI schema is documented in the FastAPI docs and the OpenAPI schema spec itself is very well documented, I think this is a decent solution, though I'd be curious to get input from others on how reliable (or not) this might be since I feel there might be sharp edges.