Harbor Swagger UI 本地开发与构建全指南基于 Webpack 的 Harbor API 文档应用【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor导读Harbor 作为开源的云原生制品仓库其对外暴露的 RESTful API 通过 Swagger/OpenAPI 规范进行描述而src/portal/app-swagger-ui/目录下的 Swagger UI 项目正是将这份 API 规范渲染成可视化交互文档的前端应用。它基于 Swagger UI 官方组件与 Webpack 构建既可在本地开发时通过代理直连 Harbor 服务端实时调试 API也可在 Docker 镜像构建阶段被打包进 portal 容器随 Harbor 一起提供/devcenter-api-2.0在线文档页面。读完本文你将掌握该应用的目录结构、开发启动流程、开发/生产两套 Webpack 配置的差异以及它如何在运行时动态注入 host、schemes 与 CSRF 防护逻辑的完整工作原理。项目定位Harbor API 文档应用的组成与角色app-swagger-ui是一个独立于主 portalAngular 应用的迷你前端工程其定位清晰可见于 package.json项目名为harbor-swagger-ui版本与 Harbor 主线版本保持一致当前仓库为2.10.0描述为 Swagger UI for Harbor APIs。它只承担一件事——将 Harbor 的 OpenAPI 规范渲染为可交互的 API 文档。该应用在 Harbor 整体架构中扮演两个角色运行时角色Harbor 部署后用户通过 portal 的/devcenter-api-2.0路径访问在线 API 文档页面由本应用编译产物提供见 make/photon/portal/Dockerfile。开发调试角色开发者可脱离 Docker 环境在本地用npm run start起一个 Webpack Dev Server把/swagger.json、/swagger2.json两个接口代理到任意 Harbor 实例直接调试真实 API。目录核心文件一览文件作用package.json依赖声明与build/start脚本入口src/index.js应用入口拉取 swagger.json、初始化 SwaggerUI、注入 CSRF 拦截器index.htmlHTML 模板含加载动画与#swagger-ui-container挂载点webpack.dev.js.temp开发配置模板需改名启用webpack.prod.js生产构建配置含 React 兼容性处理本地开发从零启动 Swagger UI仓库 README 给出了四步启动流程下面逐条展开并结合仓库实际文件说明。第一步安装依赖npm install依赖分两类见 package.json运行时依赖swagger-ui5.32.13官方 UI 组件、css-loader^6.11.0与style-loader^4.0.0负责把 swagger-ui 的样式打进 bundle开发/构建依赖webpack^5.107.2、webpack-cli^4.10.0、webpack-dev-server^6.0.0、html-webpack-plugin^5.6.0、clean-webpack-plugin^4.0.0、copy-webpack-plugin^14.0.0。同时package.json通过overrides强制统一了react/react-dom到^18.3.1这为后续生产构建中的 React 兼容策略埋下伏笔详见第三节。第二步启用开发配置仓库只提供了webpack.dev.js.temp模板需要手动复制为正式配置cp webpack.dev.js.temp webpack.dev.js第三步修改代理目标打开webpack.dev.js把两处https://example.com替换为可用的 Harbor 服务地址。以 webpack.dev.js.temp 为例其核心是devServer.proxydevServer: { proxy: { /swagger.json: { target: https://example.com, // 改为你的 Harbor 地址如 https://harbor.example.com secure: false, // 目标为自签名 HTTPS 证书时保留 false }, /swagger2.json: { target: https://example.com, secure: false, } } },两个路径含义如下/swagger.jsonHarbor 的 v2.0 API 规范。它由构建阶段从 api/v2.0/swagger.yaml 转换而来详见第四节并随 portal 容器发布/swagger2.json另一个 API 规范副本同样由swagger.yaml生成用于兼容不同访问路径。secure: false用于跳过对目标服务器的 HTTPS 证书校验当你的 Harbor 实例使用 Harbor 自签证书或非标准 CA 证书时必须保持开启。第四步启动开发服务器npm run start对应脚本为webpack serve --open --config webpack.dev.js见 package.json会自动打开浏览器。此时页面向/swagger.json发起请求经 Webpack Dev Server 代理转发到真实 Harbor再渲染出可交互的 API 文档——即实现了前端页面 远程 Harbor 后端的联调模式。开发配置详解proxy、CopyPlugin 与 HtmlWebpackPluginwebpack.dev.js.temp 除代理外还包含entryrequire.resolve(./src/index)入口即应用逻辑module.rules.css文件经style-loadercss-loader处理把 swagger-ui 的样式内联进 JS bundleCopyPlugin把favicon.ico复制到distCleanWebpackPlugin每次构建前清空distHtmlWebpackPlugin以 index.html 为模板生成页面base href/ /保证资源路径正确#swagger-ui-container是 UI 挂载点输出dist/swagger-ui.bundle.jsmode: development。生产构建React 兼容性与产物重命名webpack.prod.js 的差异点webpack.prod.js 与开发配置相比关键差异有三mode: production产出压缩后的 bundle移除了 devServer proxy 与 CopyPluginfavicon 交由 Dockerfile 阶段处理新增了resolve.alias的 React 兼容处理注释说明了原因swagger-ui 5.28 嵌套的 React 19 已从主react-dom入口移除了createRoot而swagger-ui-bundle.js是内嵌了 React 18 的独立 UMD 构建。因此将裸导入swagger-ui重定向到该 bundle避免 React 19 带来的破坏resolve: { alias: { swagger-ui$: path.resolve(__dirname, node_modules/swagger-ui/dist/swagger-ui-bundle.js), }, },这一技巧保证生产产物在 Node 模块解析层面直接使用官方打包好的 React 18 版本规避版本兼容问题。build 脚本的两步产物处理npm run build对应脚本为见 package.jsonbuild: webpack --config webpack.prod.js mv dist/index.html dist/swagger-ui-index.html即先按生产配置构建出dist/index.html与dist/swagger-ui.bundle.js再把index.html重命名为swagger-ui-index.html。这个改名是有意为之portal 的 nginx 配置中/devcenter-api-2.0路径下的请求会回退到swagger-ui-index.html见 nginx.conf.example从而把 Swagger UI 单页应用挂在 Harbor 的 API 开发中心路径上。构建集成Docker 镜像中的 swagger.json 与产物装配该应用并非独立交付而是通过 make/photon/portal/Dockerfile 集成进 portal 容器。其关键阶段如下COPY ./api/v2.0/swagger.yaml /build_dir/swagger.yaml ... RUN node -e const yaml require(js-yaml); const fs require(fs); const swagger yaml.load(fs.readFileSync(swagger.yaml, utf8)); fs.writeFileSync(swagger.json, JSON.stringify(swagger)); ... RUN cd app-swagger-ui npm ci --unsafe-perm --no-optional --no-audit --no-fund --loglevelerror RUN cd app-swagger-ui npm run build ... COPY --fromnodeportal /build_dir/swagger.json /usr/share/nginx/html COPY --fromnodeportal /build_dir/app-swagger-ui/dist /usr/share/nginx/html整个装配链路可以总结为将仓库根目录的 api/v2.0/swagger.yamlHarbor v2.0 API 的 OpenAPI 规范拷贝进构建目录用js-yaml在 Node 侧把 YAML 转成swagger.json——这正是运行时fetch(/swagger.json)的数据来源npm ci按 lockfile 安装依赖--no-audit --no-fund为静默加速再npm run build产出dist把swagger.json和dist一并拷贝到 nginx 根目录/usr/share/nginx/html。因此最终用户在 Harbor 页面看到的 API 文档数据流是swagger.yaml→swagger.json→ 浏览器 fetch → SwaggerUI 渲染。运行时原理入口代码如何渲染与保护 API 文档真正让文档活起来的是 src/index.js它完成了四件事。1. 拉取规范并动态注入 host/schemesfetch(/swagger.json).then(value value.json()).then(res { res[host] window.location.host; const protocal window.location.protocol; res[schemes] [protocal.replace(:, )]; res.info.description res.info.description helpInfo; ... });页面加载后先请求/swagger.json然后把规范中的host覆写为当前浏览器地址、schemes覆写为当前协议并追加一段helpInfo提示。helpInfo的内容是If you want to enable basic authorization, please logout Harbor first or manually delete the cookies under the current domain.如果你想启用 Basic 认证请先退出 Harbor 登录或手动删除当前域名下的 Cookie。这保证了无论 Harbor 部署在哪个域名、使用 http 还是 https文档中的Try it out请求都会正确指向当前站点而非规范文件里写死的默认地址。2. 挂载 SwaggerUI 并开启 deepLinkingSwaggerUI({ spec: res, dom_id: #swagger-ui-container, deepLinking: true, presets: [SwaggerUI.presets.apis], ... });spec直接传入运行时规范对象而非 URL避免二次请求deepLinking: true让每个 API 操作都有可分享的锚点 URL渲染完成后移除容器上的spinnerclass隐藏 index.html 中内置的 SVG 加载动画。3. CSRF Token 的请求/响应拦截Harbor 对非安全方法POST/PUT/DELETE 等实行 CSRF 防护Swagger UI 的 Try it out 要能正常调用写接口必须带上 CSRF Token。入口代码用一对拦截器完成闭环const SAFE_METHODS [GET, HEAD, OPTIONS, TRACE]; requestInterceptor: request { const token localStorage.getItem(__csrf); const headers request.headers || {}; if (token) { if (SAFE_METHODS.indexOf(request.method.toUpperCase()) -1) { headers[X-Harbor-CSRF-Token] token; } } return request; }, responseInterceptor: response { const headers response.headers || {}; const responseToken headers[X-Harbor-CSRF-Token]; if (responseToken) { localStorage.setItem(__csrf, responseToken); } return response; },机制拆解写入任何响应的响应头若携带X-Harbor-CSRF-Token就存入localStorage的__csrf键回带发起非安全方法请求时从localStorage读取该 token 并写入请求头X-Harbor-CSRF-TokenGET/HEAD/OPTIONS/TRACE 等安全方法不携带失败兜底外层.catch把 fetch 异常打印到 console。这套设计与 Harbor 的 CSRF 中间件实现相呼应——token 由服务端在响应中下发前端负责存取与回带形成无感知的双向闭环。4. 与主 portal 的路径协同主 portal 的 proxy.config.mjs.temp 与 server/README.md 显示/swagger.json、/swagger2.json、/devcenter-api-2.0、/swagger-ui.bundle.js等路径在 Angular 开发服务器中同样会被代理到 Harbor 后端。这意味着无论是独立的 app-swagger-ui 工程还是嵌入主 portal 开发环境Swagger 相关路径都指向同一份后端资源验证了该应用与主站同源、共路径的集成关系。常见问题与调试建议页面一直转圈spinner 不消失通常是/swagger.json请求失败。检查 devServer 代理的target是否可达、目标 Harbor 的证书是否可信保持secure: false可绕过以及网络策略是否放行。Try it out 调写接口报 403/CSRF 相关错误先确认localStorage.__csrf是否存在。若为空说明尚未从响应头拿到 token可先执行一次任意 GET 请求触发responseInterceptor写入。Basic 认证提示文档页面的helpInfo已说明——启用 Basic 认证前需退出 Harbor 或清理当前域 Cookie避免 cookie 与 basic auth 同时存在导致的认证冲突。生产构建报 React 相关错误确认resolve.alias已生效指向node_modules/swagger-ui/dist/swagger-ui-bundle.js这是规避 swagger-ui 5.28 与 React 19 兼容问题的关键配置。验证构建产物执行npm run build后检查dist/下应存在swagger-ui-index.html与swagger-ui.bundle.js若两者齐备即可参照 make/photon/portal/Dockerfile 的装配方式部署到任意静态服务器。小结Harbor 的app-swagger-ui是一个小而精的工程范例开发侧通过webpack.dev.js的 proxy 实现本地页面 远程 Harbor的轻量联调生产侧通过webpack.prod.js的 alias 解决 React 兼容、通过mv重命名完成与 nginx/devcenter-api-2.0路径的挂接运行时则由 src/index.js 动态覆写 host/schemes 并完成 CSRF Token 的存取闭环。配合 make/photon/portal/Dockerfile 中swagger.yaml → swagger.json → dist → nginx的装配链路一条从 OpenAPI 规范到在线交互文档的完整生产路径清晰可见。无论是想为 Harbor 定制 API 文档、排查在线文档问题还是学习 Webpack Swagger UI 的集成套路这份工程都值得直接阅读源码参考。【免费下载链接】harborAn open source trusted cloud native registry project that stores, signs, and scans content.项目地址: https://gitcode.com/GitHub_Trending/ha/harbor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
