FastAPI应用配置base path时遇OpenAPI文档加载错误求助

错误原因分析 #

你之前的问题出在重复添加/api前缀：

• 当设置root_path="/api"时，FastAPI会自动为所有内置路径（包括docs、openapi.json）以及路由路径拼接这个前缀
• 如果你手动将docs_url="/api/docs"、openapi_url="/api/openapi.json"，最终路径会变成/api/api/docs和/api/api/openapi.json，导致文档页面找不到openapi.json文件

正确配置方法 #

根据你的使用场景，有两种可靠的配置方式：

方式一：使用root_path（适合反向代理场景） #

如果你的服务后面有反向代理（比如Nginx）将/api/*转发到FastAPI，推荐用这种方式：

from fastapi import FastAPI
from routers import router_1

# root_path指定基础路径，docs_url和openapi_url只需写相对路径
app = FastAPI(
    root_path="/api",
    docs_url="/docs",       # 实际访问路径：127.0.0.1:8000/api/docs
    openapi_url="/openapi.json"  # 实际访问路径：127.0.0.1:8000/api/openapi.json
)

# 路由无需额外加前缀，root_path会自动拼接
app.include_router(router_1)

此时你的接口路径会自动变为127.0.0.1:8000/api/router_1/endpoint_1，文档页面也能正常加载openapi.json。

方式二：使用路由前缀（适合直接运行服务） #

如果不需要反向代理，直接通过FastAPI服务暴露/api路径，推荐给所有路由统一加前缀：

from fastapi import FastAPI
from routers import router_1

# 直接指定docs和openapi的完整路径，同时给路由添加prefix
app = FastAPI(
    docs_url="/api/docs",
    openapi_url="/api/openapi.json"
)

# 给每个路由添加/api前缀
app.include_router(router_1, prefix="/api")

这种方式下，所有接口路径会带上/api前缀，文档页面也能正常访问。

验证方法 #

启动服务后，访问127.0.0.1:8000/api/docs，如果能正常加载文档并看到接口路径都是/api/xxx，说明配置正确。

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