FastAPI从v0.89.1升级至v0.110.0后访问/docs出现404错误求助

以下是针对该问题的排查和解决步骤：

• 检查文档路由是否被禁用
  查看FastAPI实例的初始化代码，确认是否意外设置了docs_url=None或openapi_url=None参数。升级后如果代码中新增了这些配置，会直接关闭文档路由：

  # 错误示例：禁用了docs路由
  app = FastAPI(docs_url=None, openapi_url=None)
  
  # 正确示例：保留默认文档路由
  app = FastAPI()
  

• 安装Swagger UI可选依赖
  FastAPI从v0.100.0版本开始，Swagger UI（即/docs页面）的静态资源不再默认包含在基础安装包中。需要安装对应的可选依赖：

  pip install fastapi[swagger-ui]
  

  安装完成后重启服务，再访问/docs路径。

• 验证OpenAPI基础端点
  先尝试访问/openapi.json路径：

  • 如果该路径也返回404，说明OpenAPI文档生成失败，需检查是否存在路由定义错误、全局依赖初始化异常，或是应用实例未正确加载路由。
  • 如果/openapi.json能正常返回JSON内容，说明问题仅出在Swagger UI的静态资源加载上，回到前一步检查依赖配置。

• 排查应用挂载或路由前缀问题
  如果你的FastAPI应用是作为子应用挂载到主应用下（比如main_app.mount("/api", sub_app)），文档路径会变为/api/docs，而非根路径的/docs。此时需使用正确的前缀路径访问。

• 确认服务启动命令正确性
  检查Uvicorn启动命令是否指向了正确的应用实例，比如：

  # 正确示例：指向main.py中的app实例
  uvicorn main:app --host 0.0.0.0 --port 8000 --reload
  

  若实例名写错（比如写成main:application），会启动一个空的FastAPI应用，导致所有路径返回404。

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