FastAPI可选布尔参数Swagger文档不显示类型（Python3.12.1）

在Python 3.12.1环境下，使用FastAPI编写/sales接口时，将可选参数param的类型定义为bool | None，但Swagger自动生成的文档中该参数未显示对应的数据类型；相同代码在Python 3.9环境下则无此问题。

代码示例：

from fastapi import FastAPI
from datetime import date

app = FastAPI()

@app.get("/sales")
def sales(
    date_from: date, 
    date_to: date,
    param: bool | None = None,
):
    return date_from, date_to, param

问题截图：

方案1：改用typing.Union定义联合类型 #

Python 3.10+引入的bool | None原生联合类型语法，在部分旧版本FastAPI中对Python 3.12的兼容性存在问题，替换为typing.Union即可解决：

from fastapi import FastAPI
from datetime import date
from typing import Union

app = FastAPI()

@app.get("/sales")
def sales(
    date_from: date, 
    date_to: date,
    param: Union[bool, None] = None,
):
    return date_from, date_to, param

方案2：升级FastAPI到最新稳定版 #

该问题本质是FastAPI对Python 3.12原生联合类型的支持不完善，升级到最新版本的FastAPI即可修复兼容性问题：

pip install --upgrade fastapi

方案3：使用Annotated明确标注类型（可选） #

如果需要更严谨的类型定义，可以结合typing.Annotated来确保Swagger文档正确识别参数类型：

from fastapi import FastAPI
from datetime import date
from typing import Annotated, Union

app = FastAPI()

@app.get("/sales")
def sales(
    date_from: date, 
    date_to: date,
    param: Annotated[Union[bool, None], None] = None,
):
    return date_from, date_to, param

内容的提问来源于stack exchange，提问作者Leonidktoto