FastAPI使用T | None注解时文档不显示查询参数类型的解决办法

直接用int | None = None或者Optional[int] = None作为参数注解时，FastAPI的OpenAPI文档可能无法正确识别参数类型，以下是保留默认值None同时让客户端知晓参数类型的解决方法：

• 用Query显式声明参数
  通过Query类包裹默认值，明确参数的类型信息，这样OpenAPI文档会正确生成类型标注。示例代码：

  from fastapi import FastAPI, Query
  
  app = FastAPI()
  
  @app.get("/items/")
  async def read_items(min_price: int | None = Query(None)):
      return {"min_price": min_price}
  

• 升级FastAPI版本
  若你使用的是旧版FastAPI，可能对PEP 604的int | None联合类型支持不足，执行以下命令升级到最新稳定版：

  pip install --upgrade fastapi uvicorn
  

• 兼容旧版类型注解的写法
  如果你习惯使用typing.Optional，配合Query同样能解决问题：

  from typing import Optional
  from fastapi import FastAPI, Query
  
  app = FastAPI()
  
  @app.get("/items/")
  async def read_items(min_price: Optional[int] = Query(None)):
      return {"min_price": min_price}
  

原理说明：直接赋值None作为默认值时，FastAPI可能无法从注解中提取完整的类型元数据；而通过Query显式声明后，会强制生成包含类型信息的OpenAPI文档，同时保留参数的可选性。

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