在 FastAPI 生成的 OpenAPI 文档中更改模式名称

Question

I'm using FastAPI to create backend for my project. I have a method that allows to upload a file. I implemented it as follows:

from fastapi import APIRouter, UploadFile, File

from app.models.schemas.files import FileInResponse

router = APIRouter()


@router.post("", name="files:create-file", response_model=FileInResponse)
async def create(file: UploadFile = File(...)) -> FileInResponse:
    pass

As you can see, I use a dedicated pydantic model for a method result— FileInResponse :

from pathlib import Path

from pydantic import BaseModel


class FileInResponse(BaseModel):
    path: Path

And I follow this naming pattern for models (naming models as <Entity>InCreate , <Entity>InResponse , and so on) throughout the API. However, I couldn't create a pydantic model with a field of the type File , so I had to declare it directly in the route definition (ie without a model containing it). As a result, I have this long auto generated name Body_files_create_file_api_files_post in the OpenAPI docs:

Is there a way to change the schema name?

Answer 1

If you take a look at response model you see this :

It receives the same type you would declare for a Pydantic model atribute, so it can be a Pydantic model, but it can also be, eg a list of Pydantic models, like List[Item].

FastAPI will use this response_model to:

Convert the output data to its type declaration.
Validate the data.
Add a JSON Schema for the response, in the OpenAPI path operation.
Will be used by the automatic documentation systems.

That mean that response model is use to return json not a file like you want to do.

I couldn't create a pydantic model with a field of the type File

This is totaly normal

so I had to declare it directly in the route definition (ie without a model containing it)

And that's normal too, remember that File is not a python type nor a pydantic specific type so it can't be part of a model inheritating from pydantic BaseModel.

To do a file response you can follow the official doc :

from fastapi import FastAPI
from fastapi.responses import FileResponse

some_file_path = "large-video-file.mp4"
app = FastAPI()


@app.get("/")
async def main():
    return FileResponse(some_file_path)

if you want to return a file like object (ie file from an instance ofUploadFile ) follow this part of the doc:

from fastapi import FastAPI
from fastapi.responses import StreamingResponse

some_file_path = "large-video-file.mp4"
app = FastAPI()


@app.get("/")
def main():
    def iterfile():
        with open(some_file_path, mode="rb") as file_like:
            yield from file_like

    return StreamingResponse(iterfile(), media_type="video/mp4")