FastAPI无法访问Swagger API文档问题求助

项目目录结构 #

.
├── .env
│   ├── Include
│   ├── Lib
│   ├── Scripts
│   └── pyvenv.cfg
├── .vscode
│   └── launch.json
└── src
    ├── __pycache__
    └── main.py

main.py 代码 #

import fastapi
from fastapi import FastAPI

app=FastAPI()

@app.get("/")
def health():
    return "ok"

@app.get("/version")
def version():
    return fastapi.__version__

启动命令 #

uvicorn main:app --port 9090 --root-path src --reload

问题现象 #

API 请求可正常执行，但访问 Swagger 文档时出现fetch error，日志信息如下：

INFO:     127.0.0.1:50659 - "GET /docs HTTP/1.1" 200 OK
INFO:     127.0.0.1:50659 - "GET /src/openapi.json HTTP/1.1" 404 Not Found

使用版本：python v3.10.5、fastapi v0.85.0

问题核心是 --root-path 配置与 FastAPI 文档资源路径不匹配，可通过以下两种方式解决：

方式一：调整工作目录启动服务 #

直接进入 src 目录后启动，无需指定 --root-path：

cd src
uvicorn main:app --port 9090 --reload

此时访问 http://localhost:9090/docs 即可正常加载 Swagger 文档，openapi.json 会从正确的根路径 /openapi.json 获取。

方式二：同步 FastAPI 初始化与启动命令的 root_path 配置 #

如果必须在项目根目录启动服务，需要同时在代码和启动命令中统一 root_path：

1. 修改 main.py，初始化 FastAPI 时指定 root_path：

import fastapi
from fastapi import FastAPI

# 统一设置 root_path
app=FastAPI(root_path="/src")

@app.get("/")
def health():
    return "ok"

@app.get("/version")
def version():
    return fastapi.__version__

2. 启动命令保持并修正 --root-path 格式：

uvicorn main:app --port 9090 --root-path /src --reload

此时访问 http://localhost:9090/src/docs 即可正常加载文档，openapi.json 会从 /src/openapi.json 正确获取。

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