VSCode 无法直接预览 FastAPI 的 Swagger UI，因其仅编辑代码而不运行服务；需启动 Uvicorn 服务后手动访问 http://127.0.0.1:8000/docs，常见问题包括服务未启动、app 实例作用域错误、docs_url 被禁用、网络配置不当或静态资源加载失败。
VSCode 本身不提供 FastAPI 的内嵌 Swagger UI 预览能力——它只负责编辑，不运行服务，也不托管 /docs 页面。所谓“在 VSCode 里点开 Swagger 文档”，本质是启动 FastAPI 后访问本地 HTTP 地址，和浏览器行为完全一致。
为什么点不开 http://127.0.0.1:8000/docs？
这不是 VSCode 插件没装对，而是 Uvicorn 根本没跑起来，或服务启动失败后被静默忽略。
-
uvicorn进程退出但终端没报错：检查是否漏了--reload或路径写错（比如main:app写成main.py:app） - 终端显示
INFO: Uvicorn running on http://127.0.0.1:8000，但浏览器打不开：大概率是app = FastAPI()被包在if __name__ == "__main__":里，Uvicorn 导入不到实例 - 能打开
/redoc但/docs白屏：说明 Swagger UI 静态资源加载失败，常见于 WSL2 或 Docker 环境未加--host 0.0.0.0，导致前端 JS 请求跨域被拦截 - 用
fastapi dev启动却提示 command not found：没全局安装fastapi-cli，改用uvicorn demo.main:app --reload更可靠
docs_url=None 或 docs_url="" 导致文档消失
FastAPI 默认启用 /docs，但显式设为 None 或空字符串会彻底关闭该路由，VSCode 里再怎么刷新也看不到。
- 检查
main.py是否写了app = FastAPI(docs_url=None)—— 删除这行或改成docs_url="/docs" - 如果用了
.env文件控制配置，确认DEBUG=True没被覆盖，否则docs_url和redoc_url默认为None -
app = FastAPI(docs_url="/apidocs")是合法的，但你要手动访问http://127.0.0.1:8000/apidocs，不是默认地址
VSCode 里想“一键预览”，得靠终端 + 浏览器配合
没有插件能真正把 Swagger UI 嵌进 VSCode 编辑器窗口；所谓“集成”，只是快捷启动服务 + 自动唤起浏览器。
- 在
.vscode/launch.json中配好调试配置，args必须含--host 127.0.0.1 --port 8000（别用0.0.0.0，调试时容易连不上） - 添加自定义任务：
.vscode/tasks.json里写一个shell类型任务，命令为uvicorn main:app --reload --port 8000，并设"isBackground": true - 浏览器访问前，先确认终端输出里有
INFO: Application startup complete—— 没这句代表中间件（如 Swagger 注册）没加载成功 - 不要依赖右键菜单“Open in Browser”：它只对静态 HTML 有效，对
http://地址无效；手动复制粘贴到浏览器最稳
最容易被忽略的一点：FastAPI 的 /docs 不是 VSCode 的功能，它是运行时由 Uvicorn 提供的 HTTP 服务端点。你看到的 Swagger UI，实际是 FastAPI 自动生成并托管的前端页面——VSCode 只是帮你敲了启动命令而已。任何“预览失效”问题，90% 要回退到服务日志和网络请求层面查，而不是调插件设置。
