FastAPI中search参数类型注解未在Swagger显示的原因排查

问题场景 #

你的FastAPI端点代码如下：

@router.get("/", response_model=Page[DeviceConfigSchemaOUT])
async def get_device_configs(
    search: str | None = None,
    page: int = 1,
    size: int = 50,
) -> Any:
    ...

使用FastAPI 0.109.2 + Python 3.12.1时，Swagger文档中search参数无类型标注，尝试用Annotation手动指定类型也无效。

原因分析 #

1. 版本兼容性问题：FastAPI 0.109.2属于较早版本，对Python 3.12的str | None联合类型语法支持不完善，导致生成OpenAPI文档时无法识别该参数类型。
2. 缺少显式参数声明：未使用Query类显式声明参数元数据，旧版本FastAPI对无显式声明的可选联合类型，在文档生成阶段容易出现类型识别遗漏。
3. Annotation使用方式错误：若仅用Annotation包裹类型而未结合Query，旧版本FastAPI依然无法正确提取类型信息用于文档生成。

解决方法 #

• 升级FastAPI版本：将FastAPI升级到0.110.0及以上版本，新版本已修复对Python 3.12类型语法的解析问题，能正确识别str | None并生成对应文档标注。
• 显式使用Query声明参数：修改参数定义，通过Query强制声明类型与元数据：

  from fastapi import Query
  
  async def get_device_configs(
      search: str | None = Query(None, description="搜索关键词"),
      page: int = Query(1, ge=1),
      size: int = Query(50, ge=1, le=100),
  ) -> Any:
      ...
  

• 改用Optional[str]语法：若暂时无法升级版本，可导入typing.Optional替代管道类型语法：

  from typing import Optional
  
  async def get_device_configs(
      search: Optional[str] = None,
      page: int = 1,
      size: int = 50,
  ) -> Any:
      ...
  

  旧版本FastAPI对Optional类型的兼容性更好，能正常生成Swagger文档中的类型标注。

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