Swagger UI 本地化部署，解决 FastAPI Swagger UI 依赖外部 CDN 加载失败问题

FastAPI 默认集成的 Swagger UI 依赖 cdn.jsdelivr.net 外部 CDN 加载核心静态资源，但在实际开发中，常因外部 CDN 访问不稳定、企业内网 / 隔离环境无法访问外网等场景，导致 Swagger UI 出现加载失败、访问超时甚至页面空白等问题。为保障接口文档的访问速度与稳定性，彻底摆脱外部资源依赖，可将 Swagger UI 静态资源手动下载 并本地化部署，既保留原 /docs 接口文档的访问路径，又能实现无外部网络依赖的稳定访问。

步骤 1：创建本地静态资源目录

FastAPI 项目基础目录如下：

复制代码

your-project/
├── app/
│   ├── api/        # 接口路由模块
│   ├── core/       # 核心配置/枚举/工具
│   ├── schemas/    # 数据模型
│   ├── __init__.py
│   └── main.py     # FastAPI 应用入口
├── pyproject.toml/requirements.txt  # 依赖清单

在app目录下创建静态资源目录，专门存放 Swagger UI 文件，路径为项目根目录\app\static\swagger，目录结构如下：

复制代码

app/
└── static/        # 所有本地静态资源根目录
    └── swagger/   # Swagger UI专属目录，存放核心静态文件

步骤 2：下载 Swagger UI 静态核心文件

无需下载完整 Swagger UI 包，仅需 3 个核心文件即可实现文档正常运行，推荐下载 v5.17.14 稳定版（与 FastAPI 兼容性最佳）。

下载地址：

访问 Swagger UI 官方发布页：https://github.com/swagger-api/swagger-ui/releases，下载 swagger-ui-xxx.zip 压缩包后解压。
访问 unpkg 发布页下载核心文件：
- swagger-ui-bundle.js（核心 JS）
- swagger-ui.css（核心 CSS）
- favicon-32x32.png（图标，可选）

将下载的 3 个文件全部放入 app/static/swagger目录，最终目录结构验证：

复制代码

app/static/swagger/
├── swagger-ui-bundle.js
├── swagger-ui.css
└── favicon-32x32.png

步骤 3：修改 FastAPI 入口文件（main.py）

替换 / 补充app/main.py中的内容，关闭 FastAPI 默认/docs路由，挂载本地静态资源，重写/docs路由指向本地 Swagger UI 文件，保持原访问地址不变。

python 复制代码

from fastapi import FastAPI
from fastapi.openapi.docs import get_swagger_ui_html  # 导入Swagger UI渲染函数
from fastapi.staticfiles import StaticFiles           # 导入静态资源管理工具
from pathlib import Path                              # 导入跨平台路径处理工具

# 1. 创建FastAPI应用实例，关闭默认/docs路由
app = FastAPI(
    title="FastApi",
    version=settings.APP_VERSION,
    description=settings.APP_DESCRIPTION,
    docs_url=None,  # 关键：关闭默认/docs，避免路由冲突
    redoc_url="/redoc"  # 保留Redoc文档（可选，可设为None关闭）
)

# 2. 挂载本地Swagger UI静态资源（核心配置）
# 2.1 计算本地swagger目录的绝对路径（跨平台兼容，避免相对路径错误）
current_file_dir = Path(__file__).parent  # 获取main.py所在的app/目录绝对路径
swagger_static_dir = current_file_dir / "static" / "swagger"  # 拼接swagger目录路径

# 2.2 挂载静态资源：URL路径 /static/swagger 映射到本地swagger_static_dir目录
app.mount(
    path="/static/swagger",
    app=StaticFiles(directory=swagger_static_dir),  # 指向本地静态文件目录
    name="swagger_static"  # 静态资源别名，无实际业务意义，唯一即可
)

# 3. 重写/docs路由，使用本地静态资源渲染Swagger UI
@app.get("/docs", include_in_schema=False)  # include_in_schema=False：不将该路由加入接口文档
async def custom_swagger_ui_html():
    return get_swagger_ui_html(
        openapi_url=app.openapi_url,  # 自动指向FastAPI默认的/openapi.json（接口描述文件）
        title=f"{app.title} - Swagger UI",  # 文档页面标题，拼接项目名称
        swagger_js_url="/static/swagger/swagger-ui-bundle.js",
        swagger_css_url="/static/swagger/swagger-ui.css",
        swagger_favicon_url="/static/swagger/favicon-32x32.png",
    )

路径计算 ：使用Path(__file__).parent获取main.py所在目录的绝对路径，避免硬编码路径导致的跨平台问题（Windows/Linux/Mac 均兼容）；
静态资源挂载 ：app.mount实现「URL 路径」到「本地目录」的映射，前端访问/static/swagger/xxx时，FastAPI 会从本地app/static/swagger目录读取对应文件；
路由重写 ：@app.get("/docs")保证原访问地址不变，get_swagger_ui_html函数通过指定本地 JS/CSS 文件路径，实现脱离外部 CDN 的渲染。

步骤 4：重启 FastAPI 服务并验证

使用项目原有启动方式启动服务，示例命令：
python 复制代码
```
python app/main.py
```
打开浏览器，访问原文档地址 ：http://127.0.0.1:8000/docs（根据项目配置的 HOST/PORT 调整），若 Swagger UI 页面正常加载，且能看到项目的接口文档，说明本地化部署成功。
验证无外部 CDN 依赖：
1. 打开浏览器开发者工具（F12），切换到「网络」标签；
2. 刷新/docs页面，筛选「JS/CSS/PNG」类型文件；
3. 验证所有 Swagger 相关文件的请求地址 均为http://127.0.0.1:8000/static/swagger/xxx，无外部 CDN 域名（如cdn.jsdelivr.net、unpkg.com），且状态码均为 200。