Swagger UI 是 OpenAPI 生态中最常见的文档渲染工具，它的前端资源完全由 HTML、CSS 和 JavaScript 构成，不需要在服务器端安装 PHP、Java 或 Node.js 运行时。因此，在 Debian 上部署 Swagger UI 的核心工作就是准备一个 Web 服务器、放置静态文件、并把初始化配置指向自己的 OpenAPI 文档。相比其他文档平台，这种方式的维护成本更低，也更容易与现有 Nginx 或反向代理体系集成。下面从环境准备开始，逐步完成一个可用的 Swagger UI 服务。
一、安装 Nginx 并获取 Swagger UI 资源
在 Debian 上部署 Swagger UI，首先需要有一个能够托管静态文件的 Web 服务器。Nginx 是 Debian 仓库中自带的高性能 HTTP 服务器，资源占用低，配置直观，非常适合这类纯前端项目。先更新软件源并安装 Nginx，安装完成后可以检查服务状态，确认 Nginx 已经正常启动。
sudo apt update && sudo apt install -y nginx sudo systemctl status nginx
Swagger UI 的发布包可以从 GitHub 官方仓库直接获取。推荐下载官方 release 的压缩包，因为压缩包中已经包含了构建好的 dist 目录，无需再使用 npm 安装依赖或执行构建流程。下载解压后，把 dist 目录下的所有文件复制到网站根目录，例如 /var/www/swagger-ui。这里的路径可以根据自己的习惯调整，但后续 Nginx 配置中的 root 必须与之对应。
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.14.tar.gz tar -xzf v5.17.14.tar.gz sudo mkdir -p /var/www/swagger-ui sudo cp -r swagger-ui-5.17.14/dist/* /var/www/swagger-ui/
复制完成后进入 /var/www/swagger-ui 目录观察文件结构。核心文件包括 index.html、swagger-ui.css、swagger-ui-bundle.js 以及 swagger-initializer.js。其中 swagger-initializer.js 是较新版本中真正负责初始化 Swagger UI 实例的脚本，它决定了页面加载时会请求哪个 OpenAPI 规范文件。理解这一点对后续自定义配置非常重要，因为很多旧教程仍然指引修改 index.html，而新版本已经将这部分逻辑拆到了单独的 JS 文件中。
二、配置 Nginx 虚拟主机
静态文件就位之后，需要创建 Nginx 虚拟主机配置，让 HTTP 请求能够正确指向 Swagger UI 的根目录。Debian 中 Nginx 的站点配置默认放在 /etc/nginx/sites-available 目录下，启用某个站点时再通过软链接添加到 sites-enabled 目录。这样可以方便地启用或停用站点，而不会影响其他配置。
server {
listen 80;
server_name _;
root /var/www/swagger-ui;
index index.html;
location / {
try_files $uri $uri/ =404;
}
location ~* \.(?:css|js|png|jpg|jpeg|gif|svg|ico|woff2?)$ {
expires 7d;
add_header Cache-Control "public, no-transform";
}
}
上面的配置中，try_files 指令可以保证前端路由刷新时不会直接返回 404。虽然 Swagger UI 通常只有一个主页面，但很多场景下会使用 URL 参数指定不同文档，因此这类兜底规则仍然有意义。静态资源的缓存策略设置为 7 天，可以减轻服务器压力，同时避免开发阶段频繁修改文件后浏览器仍然使用旧缓存。正式环境如果需要更强缓存，可以适当延长过期时间。
创建配置文件后，使用软链接启用站点，然后测试 Nginx 配置语法并重新加载服务。如果测试输出中提示 syntax is ok，就说明配置文件没有语法错误。此时在浏览器中访问服务器 IP，应该已经能够看到 Swagger UI 的默认示例文档界面。
sudo ln -s /etc/nginx/sites-available/swagger-ui /etc/nginx/sites-enabled/ sudo nginx -t && sudo systemctl reload nginx
三、接入 OpenAPI 规范文件
默认情况下，Swagger UI 加载的是 Petstore 示例文档。要让页面展示自己的 API 文档，需要把 OpenAPI 规范文件放到服务器上，并修改初始化配置。最常见的方式是上传一个 openapi.yaml 或 openapi.json 文件到 /var/www/swagger-ui 目录下，然后编辑 swagger-initializer.js，将 url 参数改为相对路径或绝对路径。
window.onload = function() {
window.ui = SwaggerUIBundle({
url: "./openapi.yaml",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
});
};
修改完成后刷新页面，Swagger UI 就会尝试从指定的相对路径加载规范文件。如果页面仍然显示 Petstore 文档，可以先检查浏览器缓存，或者使用浏览器开发者工具查看实际发出的网络请求。除了修改初始化脚本，也可以在访问页面时通过 URL 参数动态指定文档地址，例如 /index.html?url=./openapi.yaml。这种方式不需要改动任何文件，特别适合在一台服务器上切换多个规范文件，也方便测试不同版本的接口文档。
如果使用的是 YAML 格式的 OpenAPI 文件，Nginx 需要正确返回对应的 MIME 类型。Debian 默认安装的 Nginx 通常已经包含 yaml 类型映射，但某些精简配置或自定义编译版本可能没有。若浏览器收到的是 text/plain 或其他类型，Swagger UI 可能无法正确解析。此时可以在 Nginx 的 http 块中手动添加类型映射，然后重新加载服务。
http {
types {
application/yaml yaml yml;
application/json json;
}
}
四、使用 Docker 部署 Swagger UI
如果不想手动管理 Nginx 和静态文件，也可以使用官方提供的 Swagger UI Docker 镜像。镜像内部已经包含 Nginx 和 Swagger UI 静态资源，只需要把 OpenAPI 规范文件挂载到容器中，并通过环境变量指定文件路径即可。这种方式尤其适合快速验证、临时分享文档，以及在开发环境中与后端服务一起通过 docker compose 启动。
docker run -d --name swagger-ui -p 8080:8080 \ -e SWAGGER_JSON=/app/openapi.yaml \ -v /opt/openapi.yaml:/app/openapi.yaml \ swaggerapi/swagger-ui
上面的命令将宿主机上的 /opt/openapi.yaml 挂载到容器内，并通过 SWAGGER_JSON 环境变量告诉 Swagger UI 加载这个文件。容器启动后，访问 http://服务器IP:8080 即可看到文档页面。如果规范文件不是 JSON 而是 YAML，也完全支持，只要文件内容符合 OpenAPI 规范即可。除了 SWAGGER_JSON，镜像还支持 URL 环境变量，用于指向一个外部可访问的规范文件地址，适用于文档由其他服务动态生成的场景。
对于需要长期运行的场景，docker compose 配置会更加清晰。将镜像、端口、环境变量和挂载目录都写在一个 YAML 文件中，后续启动和更新都只需执行一条命令。这种方式也能方便地加入网络配置，使 Swagger UI 与后端 API 服务处于同一 Docker 网络中，从而通过容器名访问内部接口。
services:
swagger-ui:
image: swaggerapi/swagger-ui
ports:
- "8080:8080"
environment:
SWAGGER_JSON: /app/openapi.yaml
volumes:
- ./openapi.yaml:/app/openapi.yaml
五、安全加固与常见问题
Swagger UI 本身只是文档展示工具，但如果部署在公网环境，仍然需要考虑访问控制。最简单的方式是使用 Nginx 的 allow 和 deny 指令限制来源 IP，或者通过基础认证增加一层口令保护。如果对外提供服务，推荐启用 HTTPS，可以使用 certbot 自动申请并续期证书。即使不直接暴露公网，也建议将 Swagger UI 放在反向代理之后，由统一的入口处理 TLS 和访问日志。
实际部署中经常遇到刷新页面出现 404 的问题。这通常是因为 Nginx 配置中缺少 try_files 规则，导致访问 /index.html 之外的路径时找不到对应文件。另一个常见问题是 YAML 文件无法加载，多数情况下是 MIME 类型没有被正确设置，或者文件权限不允许 Nginx 读取。还有一类问题是修改配置后页面没有变化，这往往是浏览器缓存造成的，可以通过强制刷新或禁用缓存来排查。使用 journalctl -u nginx 可以查看 Nginx 错误日志，快速定位请求失败的原因。
sudo journalctl -u nginx --since today sudo nginx -T | grep -n "server_name\|root\|try_files"
以上就是在 Debian 上部署 Swagger UI 的完整过程。从安装 Nginx 到接入自定义 OpenAPI 文档，再到 Docker 方案和安全加固，整体步骤并不复杂，关键在于理解静态资源托管与初始化配置之间的关系。完成部署后，后续每次接口变更只需要更新 OpenAPI 规范文件，无需重新构建前端资源，就能让团队始终看到最新的 API 文档。
DebianSwagger UIAPI文档修改时间：2026-08-22 08:00:12