OpenAPI Example with multipart/form-data not showing up

[Kludex]

Discussed in https://github.com/tiangolo/fastapi/discussions/10937

^{Originally posted by SeeRich January 11, 2024}

First Check

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

Commit to Help

• [X] I commit to help with one of those options 👆

Example Code

from typing import Annotated
from fastapi import FastAPI, UploadFile, Form, File

# Run using uvicorn main:app --reload
# Visit: http://127.0.0.1:8000/docs

app = FastAPI()

@app.post("/form-test")
async def form_test(
        str_data: Annotated[str, Form(examples=["HELLO"])],
        file: Annotated[UploadFile, File()]):
    return

Description

The HELLO example is not shown in the docs.

Operating System

Windows

Operating System Details

No response

FastAPI Version

0.108.0

Pydantic Version

2.5.3

Python Version

3.11.3

Additional Context

No response

[Kludex]

Using json_schema_extra works as expected:

from typing import Annotated
from fastapi import FastAPI, UploadFile, Form, File

# Run using uvicorn main:app --reload
# Visit: http://127.0.0.1:8000/docs

app = FastAPI()


@app.post("/form-test")
async def form_test(
    str_data: Annotated[str, Form(json_schema_extra={"example": "test"})],
    file: Annotated[UploadFile, File()],
):
    return

But using only Form(example=...) doesn't.

[ThirVondukr]

@Kludex Alias in File(alias="someAlias") doesn't seem to work either, just ran into this in my codebase 🤔

[Kludex]

@Kludex Alias in File(alias="someAlias") doesn't seem to work either, just ran into this in my codebase 🤔

• https://github.com/tiangolo/fastapi/issues/10286

[ThirVondukr]

Seems like currently you can specify json_schema_extra={"alias": alias} as a workaround

[jean0t]

If you use Forms the way you first did, it will end up in the **extra part of arguments, kwargs basically. But it is also stated in the code that this option is deprecated and also recommends to use json_schema_extra instead.

what you found might be an error because of that, so just stick to the recommended :) if you want to see more about it, just go to the file param_functions.py