FastAPI与Uvicorn不更新、文档标签缺失及状态码异常求助

1. FastAPI与Uvicorn无法更新 #

可能原因及解决办法 #

• 权限不足：直接执行升级命令可能因系统权限失败，添加--user参数安装到用户目录：

  pip install --upgrade --user fastapi uvicorn
  

• 虚拟环境未激活：若使用虚拟环境，先激活对应环境再升级，避免全局包冲突。
• 依赖冲突：旧版依赖阻碍升级时，可先卸载再重装：

  pip uninstall -y fastapi uvicorn
  pip install fastapi uvicorn
  

• pip版本过旧：老版pip不支持新包升级逻辑，先升级pip：

  pip install --upgrade pip
  

2. 接口配置的tags未在自动生成文档（docs）中显示 #

可能原因及解决办法 #

• FastAPI版本过低：旧版对tags参数支持不完善，升级到最新稳定版（参考问题1的升级方法）。
• 浏览器缓存问题：强制刷新文档页面（Ctrl+F5），避免加载旧缓存内容。
• 路由定义错误：检查路由是否重复定义或存在语法错误，示例中/blogs/和/blog/{id}/comments/{comment_id}/的tags参数配置正确，但语法错误会导致文档生成异常。
• 文档路径混淆：确认访问的是Swagger UI路径/docs，ReDoc路径/redoc对标签的展示逻辑不同。

3. 端点指定默认状态码200，但文档仅显示404和422 #

问题分析 #

你的/blog/{id}/路由虽设置了status_code=status.HTTP_200_OK，但通过response.status_code手动修改状态码的方式，FastAPI无法通过静态分析识别200状态码的返回逻辑，文档只会自动识别参数校验失败的422，以及你手动返回的404。

解决办法 #

• 使用HTTPException返回错误状态码：替代手动修改response.status_code，FastAPI会自动将异常对应的状态码纳入文档：

  from fastapi import HTTPException
  
  @app.get('/blog/{id}/', status_code=status.HTTP_200_OK)
  def get_blog(id: int):
      if id > 5:
          raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f'Blog {id} not found')
      return {"message": f'Blog with id {id}'}
  

• 显式声明所有可能的响应状态码：通过responses参数在路由中明确列出所有返回状态，文档会完整展示：

  @app.get(
      '/blog/{id}/',
      status_code=status.HTTP_200_OK,
      responses={
          200: {"description": "Blog found successfully"},
          404: {"description": "Blog not found"}
      }
  )
  def get_blog(id: int, response: Response):
      if id > 5:
          response.status_code = status.HTTP_404_NOT_FOUND
          return {'error': f'Blog {id} not found'}
      return {"message": f'Blog with id {id}'}
  

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