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

为什么需要离线文档？

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

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

准备工作

1. 克隆项目仓库到本地：

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

2. 进入项目目录并安装依赖：

   cd swagger-ui && npm install
   

构建离线资源

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

npm run build

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

配置本地API规范

1. 复制dist文件夹到目标服务器或本地目录
2. 编辑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;
   };
   

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

使用方法

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

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

构建本地镜像

1. 在项目根目录执行Docker构建命令：

   docker build -t swagger-ui-offline .
   

2. 运行容器并挂载本地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;
    }
  });
};

样式显示异常

如果界面样式错乱，通常是静态资源路径问题。确认dist目录下的css和js文件夹完整，且index.html中的资源引用路径正确。项目样式源码：style/main.scss

大文件加载优化

对于超过1MB的API规范文件，建议启用压缩：

gzip -k dist/local-api-spec.json

并在Web服务器配置中启用gzip压缩支持（Docker部署已默认配置）。

总结与最佳实践

Swagger UI提供了灵活的离线部署方案，可根据实际场景选择最合适的方式：

• 个人使用：优先选择静态文件部署，简单快捷
• 团队共享：推荐Docker容器部署，便于维护和版本控制
• 开发阶段：使用离线开发环境，支持实时编辑和预览

定期同步项目仓库获取更新：

git pull origin master && npm run build

保持本地文档工具与官方最新版本同步，获取新功能和安全更新。

Swagger UI离线模式运行界面