Swagger UI离线文档生成：无网络环境使用方案

2026-02-05 04:23:27作者：尤峻淳Whitney

为什么需要离线文档？

在企业内网、涉密环境或网络不稳定场景下，开发人员常常无法访问在线API文档工具。Swagger UI作为最流行的OpenAPI规范可视化工具，提供了完整的离线部署方案，让API文档查阅和测试摆脱网络依赖。本文将详细介绍三种实用的离线部署方式，帮助团队在无网络环境中高效使用API文档。

方案一：静态文件部署（推荐普通用户）

准备工作

克隆项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/swa/swagger-ui

进入项目目录并安装依赖：
```
cd swagger-ui && npm install
```

构建离线资源

执行构建命令生成静态文件：

npm run build

构建完成后，项目根目录下会生成dist文件夹，包含所有必要的HTML、CSS和JavaScript文件。官方文档：安装指南

配置本地API规范

复制dist文件夹到目标服务器或本地目录

编辑dist/swagger-initializer.js文件，将默认的在线API地址替换为本地文件路径：

window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "local-api-spec.json",  // 替换为本地JSON/YAML文件路径
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  });
  window.ui = ui;
};

将你的API规范文件（如openapi.json）复制到dist目录

使用方法

直接在浏览器中打开dist/index.html文件即可查看离线文档。无需Web服务器，纯静态文件运行，适合完全无网络环境。

方案二：Docker容器部署（推荐IT管理员）

构建本地镜像

在项目根目录执行Docker构建命令：
```
docker build -t swagger-ui-offline .
```

运行容器并挂载本地API规范：

docker run -p 8080:8080 \
  -v $(pwd)/local-api-spec.json:/usr/share/nginx/html/local-api-spec.json \
  -e SWAGGER_JSON=/usr/share/nginx/html/local-api-spec.json \
  swagger-ui-offline

容器配置参数

常用环境变量配置：

参数	说明	示例
`SWAGGER_JSON`	本地API规范文件路径	`-e SWAGGER_JSON=/app/api.json`
`BASE_URL`	设置基础访问路径	`-e BASE_URL=/swagger`
`DEEP_LINKING`	启用深度链接功能	`-e DEEP_LINKING=true`

完整配置项参见：配置文档

访问离线文档

在浏览器中访问http://localhost:8080即可使用。Docker方案的优势在于环境一致性和易于部署，适合团队共享使用。

方案三：离线开发环境（推荐开发人员）

本地开发服务器

启动开发服务器，即使后续断开网络也能继续使用：

npm run dev

开发服务器默认监听8080端口，通过http://localhost:8080访问。开发环境配置文件：webpack/dev.js

配置多API规范

编辑dev-helpers/swagger-config.yaml文件，添加多个本地API规范：

urls:
  - url: 'local-api-v1.json'
    name: 'API V1'
  - url: 'local-api-v2.json'
    name: 'API V2'

重启开发服务器后，顶部导航栏会显示API版本切换下拉菜单。

离线功能对比

功能	静态文件部署	Docker部署	开发环境
完全离线运行	✅	✅	❌（需首次联网安装依赖）
无需安装Node.js	✅	✅	❌
支持API测试	✅	✅	✅
多规范切换	✅	✅	✅
自动刷新	❌	❌	✅

常见问题解决

跨域问题处理

若API测试时出现跨域错误，可通过修改配置文件dist/swagger-initializer.js添加参数：

window.onload = function() {
  const ui = SwaggerUIBundle({
    // ...其他配置
    withCredentials: true,  // 启用跨域凭证
    requestInterceptor: (req) => {
      req.headers['Access-Control-Allow-Origin'] = '*';
      return req;
    }
  });
};