Fastapi: [QUESTION] 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 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. :thinking:

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