使用Nginx部署FastAPI后Swagger UI自动文档无法显示

问题核心分析 #

1. 直接访问8002/docs异常：FastAPI默认会自动生成Swagger UI（/docs），但你的情况可能是运行方式或基础配置缺失导致页面加载异常；另外gunicorn启动时不会执行代码中if __name__ == '__main__'块，需确保应用核心配置生效。
2. Nginx代理后/api3/docs异常：FastAPI不知道请求是通过/api3路径代理过来的，导致Swagger UI生成的接口请求路径错误（直接指向根路径而非/api3），引发404或加载失败。

分步解决 #

1. 修复直接访问8002/docs的问题 #

先验证基础运行是否正常：

• 直接用uvicorn启动应用：

  uvicorn main:app --host 127.0.0.1 --port 8002
  

  访问http://localhost:8002/docs，如果仍异常，显式指定OpenAPI相关配置到main.py：

  from fastapi import FastAPI
  
  app = FastAPI(
      debug=True,
      openapi_url="/openapi.json",  # 显式指定OpenAPI schema路径
      docs_url="/docs",             # 显式指定Swagger UI路径
      redoc_url="/redoc"            # 可选，指定ReDoc路径
  )
    
  @app.post("/")
  def test_docs():
      return 1
  

2. 解决Nginx代理后的Swagger路径问题 #

需要让FastAPI识别代理前缀/api3，推荐两种简单方式：

方式一：修改FastAPI初始化配置

直接在main.py中给FastAPI实例添加root_path参数：

app = FastAPI(
    debug=True,
    root_path="/api3"  # 指定代理前缀
)

这样FastAPI会自动调整Swagger UI中的接口请求路径，统一加上/api3前缀。

方式二：通过Gunicorn传递root_path

如果不想修改代码，可在gunicorn.py中添加配置：

# 新增以下配置项
root_path = "/api3"

或者启动gunicorn时加命令行参数：

gunicorn -c gunicorn.py --root-path /api3 main:app

补充：优化Nginx代理配置（可选）

给Nginx添加代理头部，确保FastAPI能正确识别请求来源：

location /api3/ {
    proxy_pass http://127.0.0.1:8002/;
    proxy_redirect off;
    # 新增代理头部
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /api3;
}

3. 验证生效 #

修改完成后重启服务：

# 重启gunicorn
pkill gunicorn && gunicorn -c gunicorn.py main:app
# 重启Nginx
sudo systemctl restart nginx

访问http://<你的服务器IP>/api3/docs，检查Swagger UI是否能正常加载并调用接口。

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