FastAPI 的 /docs 无法打开是因为 uvicorn 服务未启动或端口被占用；必须运行 uvicorn main:app --reload --port 8000 后，再访问 http://127.0.0.1:8000/docs，VSCode 无需插件即可支持。
FastAPI 自动生成的 /docs 在 VSCode 里打不开？
不是插件问题，是本地服务没跑起来或端口被占。FastAPI 的 Swagger UI（/docs）和 ReDoc（/redoc）本质是 HTTP 页面，必须先启动 uvicorn 服务才能访问。VSCode 本身不提供内置 Swagger 渲览器，它只负责代码编辑和终端控制。
常见错误现象：
- 点开
http://127.0.0.1:8000/docs显示 “This site can’t be reached” - 终端报错
OSError: [Errno 48] Address already in use - 改了代码但刷新
/docs没变化——没启用热重载
实操建议：
- 确保已安装
uvicorn：pip install uvicorn - 用命令启动并启用重载：
uvicorn main:app --reload --port 8000（main是你的 Python 文件名，app是 FastAPI 实例变量名） - 启动后直接在 VSCode 内置终端或系统浏览器中打开
http://127.0.0.1:8000/docs即可，无需额外插件
要不要装 Swagger 插件？比如 “Swagger Viewer” 或 “OpenAPI Preview”
没必要。这类插件面向的是静态 openapi.json 文件预览，而 FastAPI 动态生成的文档接口（/openapi.json）已经足够规范且实时更新。强行导出 JSON 再用插件加载，反而多一步、易过期、不支持鉴权/测试请求。
唯一适合用插件的场景：你正在协作编写 OpenAPI 3.0 规范的 YAML/JSON 文件（非 FastAPI 自动生成），需要离线校验或可视化结构。但对 FastAPI 日常开发来说，这是反模式。
注意：Swagger Viewer 插件不支持带 Cookie 或 Bearer Token 的请求调试；OpenAPI Preview 无法渲染 FastAPI 自动生成的 x-code-samples 或自定义 examples 字段。
想在 VSCode 里一键打开 /docs 页面？加个自定义任务就行
不用装插件，用 VSCode 原生 tasks.json 配合 open 命令就能实现点击运行 → 自动唤起浏览器。
操作步骤：
- 项目根目录建
.vscode/tasks.json - 填入以下内容（适配你的文件名和端口）：
{
"version": "2.0.0",
"tasks": [
{
"label": "launch-fastapi-docs",
"type": "shell",
"command": "uvicorn main:app --reload --port 8000 && open http://127.0.0.1:8000/docs",
"isBackground": true,
"problemMatcher": []
}
]
}
然后按 Ctrl+Shift+P（Win/Linux）或 Cmd+Shift+P（Mac），输入 “Tasks: Run Task”，选 launch-fastapi-docs —— 服务启动同时浏览器自动弹出 /docs。
⚠️ 注意：&& 在 Windows 的默认终端（PowerShell）里可能失效，建议把终端设为 bash 或改用 start（Windows）/open（macOS）/xdg-open（Linux）分别处理。
调试接口时发现 /docs 里参数没显示或类型错误？
根本原因不在 VSCode 或插件，而在 FastAPI 的类型注解写法。Swagger UI 完全依赖 Pydantic 模型和函数签名推导，任何含糊写法都会导致字段丢失或类型退化为 object。
典型坑点：
- 用
Dict或Any当参数类型 → Swagger 显示object，无法生成示例 - 路径参数没加类型注解，比如
def read_item(item_id)而不是def read_item(item_id: int)→ 不出现在参数列表 - 使用了
Body(..., embed=True)但没配 Pydantic 模型 → 文档里变成空字段 - 自定义
BaseModel中字段用了Optional但没给默认值 → Swagger 认为该字段必填，实际却可为空
验证方法：直接访问 http://127.0.0.1:8000/openapi.json，看 paths 下对应接口的 parameters 和 requestBody 是否结构完整。如果 JSON 里已经缺失，那前端页面必然空白——这时候修的是 Python 代码，不是 VSCode 设置。
