Swagger UI not showing optional file upload button

[jvdavim]

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

from typing import Annotated

from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.get("/")
def read_root():
    return {"Hello": "World"}


@app.post("/example")
def read_item(upload_file: Annotated[UploadFile | None, File(description="Some description")] = None):
    return

Description

For some reason, when using Python >= 3.10 optional type hints ( SomeType | None ) in endpoints methods parameters, the upload button is not rendered in the Swagger UI.
Edit: For some reason, when making an UploadFile parameter optional, the upload button is not rendered in the Swagger UI. The problem is just the same using the old typing.Optional notation or UploadFile | None.

Update: It's happening only with pydantic v2. Downgrading to pydantic v1 seems to fix the bug.

An example of working swagger UI (but wrong typing) upload button:

An example of broken swagger UI (but right typing) upload button:

Inspecting the generated openapi.json I realized that there are some differences on using the optional (SomeType | None) type hint, as seem on the screenshot below:

I'm not sure if this change is not expected, or if it's a Swagger UI related problem. I tried to find it in Swagger UI repository, but I was not successful. I'm not so experienced with openapi docs, so maybe I'm missing something. I appreciate your help.

Operating System

Linux, macOS

Operating System Details

No response

FastAPI Version

0.104.1

Pydantic Version

2.5.2

Python Version

3.11.6

Additional Context

No response

[kiraware]

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class Blog(BaseModel):
    title: str
    body: str
    published: Optional[bool] # published: bool | None, should just do the same thing


@app.post("/test")
async def create_blog(request: Blog):
    return request

This code too. Optional is fail and the published field is required in Swagger UI docs.

Or redocs

Am i miss something?

[sr2ds]

Looks that when the field is Optional for Upload type, the button is not showed on UI

[jvdavim]

You are both right. It seems not work with both typing.Optional and UploadFile | None notations. So it's not right having Python 3.10 or the new type hints notation as causes of the problem. I'm gonna edit the original post.

[sr2ds]

@jvdavim , did you try with no Annotated?:

def read_item(upload_file: UploadFile | None)

[jvdavim]

I didn't. But I'm testing right now...
It seems the problem persists.
Using def read_item(upload_file: UploadFile | None) I get Almost the same result, but without the "send empty" checkbox:

Using def read_item(upload_file: UploadFile | None = None) I get the checkbox back to the SwaggerUI, but still missing button:

[kiraware]

After some try i can make it optional. It is happen if you assign None to field in Pydantic model

...

class Blog(BaseModel):
    title: str
    body: str
    published: Optional[bool] = None # Or do with this, published: bool | None = None

...

The key is when you assign None to Pydantic model to make it optional in Swagger or redocs

class Foo(BaseModel):
    a: Optional[str] # Required
    b: str | None # Required
    c: Optional[str] | None # Required
    d: Optional[str] = None # Optional
    e: str | None = None # Optional
    f: str = None # Optional

[jvdavim]

Yes. Assigning None to the argument will definitely make it optional. Even so I have 2 considerations:

1. In your example the attribute f of the BaseModel is typed as str, but it's being set as None. The linter will show an error, because it's being set a type to the attribute which were not supposed to. So, to make it right, it should be explicitly marked as str | None.
2. I don't know yet if this behavior is expected, but IMHO making an UploadFile argument optional, shouldn't make the upload button disappear from the SwaggerUI.

[iudeen]

yes, I agree this is an issue!

[jvdavim]

I have found that it's happening only with pydantic v2. But it seems to be a problema with SwaggerUI, not FastAPI. I'm gonna try to find some issue on their repository or open a new one.

For some reason, the upload file button is not being rendered beacause SwaggerUI is not processing the AnyOf from OpenAPI 3.1 specification. Here is the swagger online editor: https://editor-next.swagger.io/. The OpenAPI 3.1.0 json produces the same result on the online editor.

[carlodri]

I have just stumbled on the same issue using fastapi 0.109.2 and pydantic 2.6.1

[niking00]

Use

@app.post("/example")
def read_item(upload_file: Annotated[UploadFile, File(description="Some description")] = None):
    return

Works for me

[jvdavim]

Yes. This works, but as I described, it's using wrong type hint. How could an UploadFile be None by default? It should be UploadFile | None.

[bpkrishnan]

Any update?

[xiaoyuan-sun]

Met same problem, any update?