Swagger UI 安装部署全指南NPM 模块、Docker 镜像与 CDN/静态托管方案详解【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui本篇指南以 Swagger UI 官方 安装文档 为核心系统讲解这个开源项目GitHub 仓库swagger-ui一个由 HTML、JavaScript 与 CSS 资产组成、可根据 Swagger 兼容的 API 定义动态生成精美文档的前端项目的全部安装与分发渠道面向打包器的npm模块、面向服务端的swagger-ui-dist、一条命令上线的 Docker 镜像以及不依赖任何构建工具的 unpkg CDN 与静态文件部署方式。读完本文你将能够根据自身项目形态前端工程、Node 服务端、容器环境还是纯静态站点选择最合适的方案并完成可运行的落地配置。发行渠道总览Swagger UI 的官方安装文档将分发渠道划分为四类分别对应不同的使用场景分发渠道适用场景是否需要构建工具NPM Registry三个模块前端工程、Node 服务端视模块而定Docker 镜像容器化部署、快速演示不需要unpkg CDN纯 HTML 页面直接嵌入不需要静态文件 / Standalone静态网站、CMS、无 npm 环境不需要下文将逐一展开每种渠道的安装步骤、核心用法与仓库内的源码佐证。NPM Registry面向不同消费方的三个模块Swagger UI 在 npm 上发布三个模块swagger-ui、swagger-ui-dist与swagger-ui-react。三者定位截然不同安装前务必先区分清楚。swagger-ui供模块打包器消费的主模块swagger-ui面向使用 Webpack、Browserify、Rollup 等模块打包器的 JavaScript 前端工程。它的主文件导出 Swagger UI 的主函数即SwaggerUI模块内还带有一个命名空间样式表swagger-ui/dist/swagger-ui.css。从当前仓库的 package.json 可以看到该模块的导出结构main: ./dist/swagger-ui.js, module: ./dist/swagger-ui-es-bundle-core.js, exports: { ./dist/swagger-ui.css: ./dist/swagger-ui.css, ./dist/oauth2-redirect.html: ./dist/oauth2-redirect.html, ./dist/swagger-ui-standalone-preset: ./dist/swagger-ui-standalone-preset.js, .: { browser: { import: ./dist/swagger-ui-es-bundle-core.js, require: ./dist/swagger-ui.js }, node: { import: ./dist/swagger-ui-bundle.js, require: ./dist/swagger-ui-es-bundle.js } } }模块会根据运行环境浏览器 / Node与模块规范import / require自动选择对应的构建产物同时显式导出了dist/swagger-ui.css与 OAuth2 重定向页dist/oauth2-redirect.html供工程按需引用。仓库的源码入口 src/index.js 只是简单地将./core重新导出主逻辑集中在src/core目录中。安装命令$ npm install swagger-ui基本用法import SwaggerUI from swagger-ui // or use require if you prefer const SwaggerUI require(swagger-ui) SwaggerUI({ dom_id: #myDomId })SwaggerUI接收一个配置对象其中dom_id指定 UI 挂载的 DOM 节点选择器。更多配置项url、spec、presets、layout等可参考 配置文档。Webpack 起步示例官方提供了完整的 Webpack Getting Started 示例演示如何用 Webpack 打包 Swagger UI 并配置 CSS 与 OAuth。其入口 src/index.js 展示了导入主模块、样式表以及调用initOAuth的完整流程import SwaggerUI from swagger-ui import swagger-ui/dist/swagger-ui.css; const spec require(./swagger-config.yaml); const ui SwaggerUI({ spec, dom_id: #swagger, }); ui.initOAuth({ appName: Swagger UI Webpack Demo, // See https://demo.identityserver.io/ for configuration details. clientId: implicit });注意两点其一swagger-ui.css通过swagger-ui/dist/swagger-ui.css路径显式引入这正是 package.jsonexports字段中暴露的命名空间路径其二示例的 webpack.config.js 通过copy-webpack-plugin把 OAuth2 重定向文件复制到构建产物根目录new CopyWebpackPlugin({patterns:[ { // Copy the Swagger OAuth2 redirect file to the project root; // that file handles the OAuth2 redirect after authenticating the end-user. from: require.resolve(swagger-ui/dist/oauth2-redirect.html), to: ./ } ]}),若你的 API 使用 OAuth2 授权流程这一步必不可少——重定向页负责在用户完成认证后把令牌回传给 Swagger UI。按示例 README 的操作说明试运行步骤为先把_sample_package.json重命名为package.json该文件仅是占位样例需自行核对swagger-ui版本是否为最新然后执行npm install与npm start即可启动开发服务器打开页面。swagger-ui-dist供服务端分发静态资产swagger-ui-dist面向需要把静态资产提供给客户端访问的服务端项目例如 Node.js 后端。模块被引入后会提供一个absolutePath辅助函数返回swagger-ui-dist模块安装位置的绝对文件系统路径。其实现可在仓库的 absolute-path.js 中看到——仅在 Node.js 环境检测module与module.exports是否存在下返回path.resolve(__dirname)在浏览器环境则会抛出错误提示const getAbsoluteFSPath function () { // detect whether we are running in a browser or nodejs if (typeof module ! undefined module.exports) { return require(path).resolve(__dirname) } throw new Error(getAbsoluteFSPath can only be called within a Nodejs environment); } module.exports getAbsoluteFSPath安装命令$ npm install swagger-ui-dist配合 Express 托管静态文件const express require(express) const pathToSwaggerUi require(swagger-ui-dist).absolutePath() const app express() app.use(express.static(pathToSwaggerUi)) app.listen(3000)启动后访问http://localhost:3000即可看到 Swagger UI 页面。关于absolutePath的命名细节查看 swagger-ui-dist-package/index.js 可以发现absolutePath与getAbsoluteFSPath两个名字同时被导出指向同一个实现。官方注释说明这是因为历史上文档写了一个名字、实际实现却是另一个为了不破坏既有使用方的代码两者都被保留。因此你在代码中看到任意一种写法都属于正常用法。SwaggerUIBundle与SwaggerUIStandalonePreset导出同一个入口文件index.js还会尝试导出SwaggerUIBundle与SwaggerUIStandalonePreset供无法直接处理传统 npm 模块的 JavaScript 项目使用var SwaggerUIBundle require(swagger-ui-dist).SwaggerUIBundle const ui SwaggerUIBundle({ url: https://petstore.swagger.io/v2/swagger.json, dom_id: #swagger-ui, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ], layout: StandaloneLayout })这里SwaggerUIBundle与SwaggerUI等价文档原文明确 SwaggerUIBundleis equivalent toSwaggerUI。presets.apis是核心 API 插件预设SwaggerUIStandalonePreset则补充了顶部导航栏TopBar等独立部署所需的组件。选型提示官方原文强调只要工具链允许建议优先使用swagger-ui因为swagger-ui-dist会把更多代码通过网络传输到客户端Note: we suggest usingswagger-uiwhen your tooling makes it possible, asswagger-ui-distwill result in more code going across the wire.。swagger-ui-reactReact 组件封装第三个模块swagger-ui-react以 React 组件形式封装 Swagger UI适合 React 应用直接以SwaggerUI /组件方式使用其组件实现在仓库的 flavors/swagger-ui-react/index.jsx 中。安装命令$ npm install swagger-ui-react具体 props 与用法以该模块随附的 README 为准。Docker一条命令部署 Swagger UI官方维护了预构建的 Docker 镜像可直接从docker.swagger.io拉取。快速启动docker pull docker.swagger.io/swaggerapi/swagger-ui docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui该命令会启动一个 nginx 容器在宿主机的 80 端口对外提供 Swagger UI容器内部端口为 8080。挂载本地的 swagger.json把宿主机上的 OpenAPI 定义文件挂载进容器并通过SWAGGER_JSON环境变量指定容器内路径docker run -p 80:8080 -e SWAGGER_JSON/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui其中-v /bar:/foo把宿主机的/bar目录挂载为容器内的/fooSWAGGER_JSON指向该挂载点下的定义文件。指定外部 URL 的定义文件也可以不挂载文件而是让 Swagger UI 直接加载外部主机的 JSONdocker run -p 80:8080 -e SWAGGER_JSON_URLhttps://petstore3.swagger.io/api/v3/openapi.json docker.swagger.io/swaggerapi/swagger-ui修改应用根路径BASE_URL默认情况下应用部署在/。通过BASE_URL环境变量可以改变 Web 应用的根路径docker run -p 80:8080 -e BASE_URL/swagger -e SWAGGER_JSON/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui这样 Swagger UI 将从/swagger路径对外提供服务而非/。自定义监听端口PORT 与 PORT_IPV6容器对外nginx 监听的端口默认为8080可用PORT覆盖IPv6 端口默认不启用可用PORT_IPV6单独指定docker run -p 80:80 -e PORT80 docker.swagger.io/swaggerapi/swagger-uidocker run -p 80:80 -e PORT_IPV68080 docker.swagger.io/swaggerapi/swagger-ui控制页面是否可被嵌入EMBEDDINGEMBEDDING变量用于允许/禁止 Swagger UI 通过 X-Frame-Options 被其他页面 iframe 嵌入默认禁止嵌入docker run -p 80:80 -e EMBEDDINGtrue docker.swagger.io/swaggerapi/swagger-ui镜像环境变量的仓库源码佐证以上环境变量的默认值全部定义在仓库根目录的 Dockerfile 中ENV API_KEY**None** \ SWAGGER_JSON/app/swagger.json \ PORT8080 \ PORT_IPV6 \ BASE_URL/ \ SWAGGER_JSON_URL \ CORStrue \ EMBEDDINGfalse可以看到除文档提到的变量外镜像还内置了API_KEY、CORS等开关CORStrue默认开启跨域支持。启动时这些变量的实际生效逻辑在 docker/docker-entrypoint.d/40-swagger-ui.sh 中实现例如存在SWAGGER_JSON_URL时用sed把初始化脚本swagger-initializer.js中默认的https://petstore.swagger.io/v2/swagger.json替换为目标 URL存在SWAGGER_JSON文件时以符号链接方式挂到 nginx 根目录并把初始化脚本中的默认 URL 替换为相对路径同时配合BASE_URL改写 nginx 的重写规则PORT_IPV6非空时向 nginx 配置追加listen [::]:${PORT_IPV6}EMBEDDING不为false时清空embedding.conf模板以允许嵌入。理解这份脚本有助于排查“为什么环境变量没生效”之类的问题。更完整的 Docker 配置入口除了上述专用变量Docker 镜像还支持用环境变量覆盖 Swagger UI 的大多数配置项字符串、布尔、数字、数组、对象五种类型均支持例如FILTERmyFilterValue、DEEP_LINKINGfalse、URLS[ { url: \...\, name: \...\ } ]、SPEC{ \openapi\: \3.0.4\ }详细规则见 Configuration 文档的 Docker 章节。如需编写 docker-compose 编排可参考同文档的Docker-Compose小节SUPPORTED_SUBMIT_METHODS[get, post]等.env文件的编码写法。unpkg在 HTML 中直接嵌入 Swagger UI如果你的页面不想引入任何构建工具可以直接通过 unpkg CDN 引用swagger-ui-dist的产物。最基础的用法是引用swagger-ui.css与swagger-ui-bundle.js后者是包含运行全部所需代码的单文件构建!DOCTYPE html html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / meta namedescription contentSwaggerUI / titleSwaggerUI/title link relstylesheet hrefhttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui.css / /head body div idswagger-ui/div script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-bundle.js crossorigin/script script window.onload () { window.ui SwaggerUIBundle({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, }); }; /script /body /html引入 StandalonePreset 增强 UI使用StandalonePreset即独立预设会额外渲染TopBar顶部搜索栏和ValidatorBadge在线校验徽标!DOCTYPE html html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / meta namedescription contentSwaggerUI / titleSwaggerUI/title link relstylesheet hrefhttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui.css / /head body div idswagger-ui/div script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-bundle.js crossorigin/script script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-standalone-preset.js crossorigin/script script window.onload () { window.ui SwaggerUIBundle({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: StandaloneLayout, }); }; /script /body /html这里SwaggerUIBundle.presets.apis提供解析与渲染 OpenAPI 定义的核心能力SwaggerUIStandalonePreset提供独立部署的完整界面layout: StandaloneLayout指定使用独立布局。这与上一节swagger-ui-dist在 Node 中require出来的配置结构完全一致只是加载方式从模块系统换成了script标签。静态文件方式无 HTTP 服务器托管官方文档还提供了一种完全脱离 HTTP/HTML 的用法一旦 Swagger UI 成功构建出/dist目录你可以把它直接拷贝到自己的文件系统中由任意静态文件服务器托管。这里提到的/dist是仓库构建产物目录——构建脚本见 package.jsonnpm run build会依次构建样式表与各类 bundle构建完成后 dist 目录中包含swagger-ui-bundle.js、swagger-ui.css、swagger-ui-standalone-preset.js以及oauth2-redirect.html等关键资产。纯 HTML/CSS/JS 独立部署Standalone无需 npm如果目标环境如静态网站、CMS完全没有 npm最直接的方式是使用官方发布的 Standalone 产物下载 最新 release 的version字段将/dist目录中的内容复制到你的服务器用文本编辑器打开swagger-initializer.js把其中的https://petstore.swagger.io/v2/swagger.json替换为你自己的 OpenAPI 3.0 规范文件 URL。swagger-initializer.js是容器镜像与 Standalone 部署共用的初始化入口参见 docker/docker-entrypoint.d/40-swagger-ui.sh 中对它的sed替换逻辑它负责在页面加载时调用SwaggerUIBundle并注入你的定义地址。仓库的 dev-helpers/index.html 亦展示了类似的本地开发页结构可作为参考。结语如何选择安装方式综合以上四类渠道可以按以下规则快速决策前端工程有 Webpack/Rollup 等打包器→ 选swagger-ui并按需引入dist/swagger-ui.css与oauth2-redirect.html参考 Webpack Getting Started 示例Node 服务端需要托管静态页面→ 选swagger-ui-dist用absolutePath()拿到安装路径后交给express.static等中间件容器化 / 快速部署→ 拉取docker.swagger.io/swaggerapi/swagger-ui镜像配合SWAGGER_JSON、SWAGGER_JSON_URL、BASE_URL、PORT、PORT_IPV6、EMBEDDING等环境变量完成定制纯 HTML 页面 / 无构建环境→ 用 unpkg CDN 引入swagger-ui-bundle.js或下载 release 产物把/dist拷贝到服务器并编辑swagger-initializer.js。无论选择哪条路径初始化配置的核心都是SwaggerUI({ url / spec, dom_id, presets, layout })这一套对象结构掌握它即可在所有场景间平滑迁移。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/11 6:17:06 · 阅读 1.2k Swagger UI 安装部署全指南：NPM 模块、Docker 镜像与 CDN/静态托管方案详解
Swagger UI 安装部署全指南NPM 模块、Docker 镜像与 CDN/静态托管方案详解【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui本篇指南以 Swagger UI 官方 安装文档 为核心系统讲解这个开源项目GitHub 仓库swagger-ui一个由 HTML、JavaScript 与 CSS 资产组成、可根据 Swagger 兼容的 API 定义动态生成精美文档的前端项目的全部安装与分发渠道面向打包器的npm模块、面向服务端的swagger-ui-dist、一条命令上线的 Docker 镜像以及不依赖任何构建工具的 unpkg CDN 与静态文件部署方式。读完本文你将能够根据自身项目形态前端工程、Node 服务端、容器环境还是纯静态站点选择最合适的方案并完成可运行的落地配置。发行渠道总览Swagger UI 的官方安装文档将分发渠道划分为四类分别对应不同的使用场景分发渠道适用场景是否需要构建工具NPM Registry三个模块前端工程、Node 服务端视模块而定Docker 镜像容器化部署、快速演示不需要unpkg CDN纯 HTML 页面直接嵌入不需要静态文件 / Standalone静态网站、CMS、无 npm 环境不需要下文将逐一展开每种渠道的安装步骤、核心用法与仓库内的源码佐证。NPM Registry面向不同消费方的三个模块Swagger UI 在 npm 上发布三个模块swagger-ui、swagger-ui-dist与swagger-ui-react。三者定位截然不同安装前务必先区分清楚。swagger-ui供模块打包器消费的主模块swagger-ui面向使用 Webpack、Browserify、Rollup 等模块打包器的 JavaScript 前端工程。它的主文件导出 Swagger UI 的主函数即SwaggerUI模块内还带有一个命名空间样式表swagger-ui/dist/swagger-ui.css。从当前仓库的 package.json 可以看到该模块的导出结构main: ./dist/swagger-ui.js, module: ./dist/swagger-ui-es-bundle-core.js, exports: { ./dist/swagger-ui.css: ./dist/swagger-ui.css, ./dist/oauth2-redirect.html: ./dist/oauth2-redirect.html, ./dist/swagger-ui-standalone-preset: ./dist/swagger-ui-standalone-preset.js, .: { browser: { import: ./dist/swagger-ui-es-bundle-core.js, require: ./dist/swagger-ui.js }, node: { import: ./dist/swagger-ui-bundle.js, require: ./dist/swagger-ui-es-bundle.js } } }模块会根据运行环境浏览器 / Node与模块规范import / require自动选择对应的构建产物同时显式导出了dist/swagger-ui.css与 OAuth2 重定向页dist/oauth2-redirect.html供工程按需引用。仓库的源码入口 src/index.js 只是简单地将./core重新导出主逻辑集中在src/core目录中。安装命令$ npm install swagger-ui基本用法import SwaggerUI from swagger-ui // or use require if you prefer const SwaggerUI require(swagger-ui) SwaggerUI({ dom_id: #myDomId })SwaggerUI接收一个配置对象其中dom_id指定 UI 挂载的 DOM 节点选择器。更多配置项url、spec、presets、layout等可参考 配置文档。Webpack 起步示例官方提供了完整的 Webpack Getting Started 示例演示如何用 Webpack 打包 Swagger UI 并配置 CSS 与 OAuth。其入口 src/index.js 展示了导入主模块、样式表以及调用initOAuth的完整流程import SwaggerUI from swagger-ui import swagger-ui/dist/swagger-ui.css; const spec require(./swagger-config.yaml); const ui SwaggerUI({ spec, dom_id: #swagger, }); ui.initOAuth({ appName: Swagger UI Webpack Demo, // See https://demo.identityserver.io/ for configuration details. clientId: implicit });注意两点其一swagger-ui.css通过swagger-ui/dist/swagger-ui.css路径显式引入这正是 package.jsonexports字段中暴露的命名空间路径其二示例的 webpack.config.js 通过copy-webpack-plugin把 OAuth2 重定向文件复制到构建产物根目录new CopyWebpackPlugin({patterns:[ { // Copy the Swagger OAuth2 redirect file to the project root; // that file handles the OAuth2 redirect after authenticating the end-user. from: require.resolve(swagger-ui/dist/oauth2-redirect.html), to: ./ } ]}),若你的 API 使用 OAuth2 授权流程这一步必不可少——重定向页负责在用户完成认证后把令牌回传给 Swagger UI。按示例 README 的操作说明试运行步骤为先把_sample_package.json重命名为package.json该文件仅是占位样例需自行核对swagger-ui版本是否为最新然后执行npm install与npm start即可启动开发服务器打开页面。swagger-ui-dist供服务端分发静态资产swagger-ui-dist面向需要把静态资产提供给客户端访问的服务端项目例如 Node.js 后端。模块被引入后会提供一个absolutePath辅助函数返回swagger-ui-dist模块安装位置的绝对文件系统路径。其实现可在仓库的 absolute-path.js 中看到——仅在 Node.js 环境检测module与module.exports是否存在下返回path.resolve(__dirname)在浏览器环境则会抛出错误提示const getAbsoluteFSPath function () { // detect whether we are running in a browser or nodejs if (typeof module ! undefined module.exports) { return require(path).resolve(__dirname) } throw new Error(getAbsoluteFSPath can only be called within a Nodejs environment); } module.exports getAbsoluteFSPath安装命令$ npm install swagger-ui-dist配合 Express 托管静态文件const express require(express) const pathToSwaggerUi require(swagger-ui-dist).absolutePath() const app express() app.use(express.static(pathToSwaggerUi)) app.listen(3000)启动后访问http://localhost:3000即可看到 Swagger UI 页面。关于absolutePath的命名细节查看 swagger-ui-dist-package/index.js 可以发现absolutePath与getAbsoluteFSPath两个名字同时被导出指向同一个实现。官方注释说明这是因为历史上文档写了一个名字、实际实现却是另一个为了不破坏既有使用方的代码两者都被保留。因此你在代码中看到任意一种写法都属于正常用法。SwaggerUIBundle与SwaggerUIStandalonePreset导出同一个入口文件index.js还会尝试导出SwaggerUIBundle与SwaggerUIStandalonePreset供无法直接处理传统 npm 模块的 JavaScript 项目使用var SwaggerUIBundle require(swagger-ui-dist).SwaggerUIBundle const ui SwaggerUIBundle({ url: https://petstore.swagger.io/v2/swagger.json, dom_id: #swagger-ui, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset ], layout: StandaloneLayout })这里SwaggerUIBundle与SwaggerUI等价文档原文明确 SwaggerUIBundleis equivalent toSwaggerUI。presets.apis是核心 API 插件预设SwaggerUIStandalonePreset则补充了顶部导航栏TopBar等独立部署所需的组件。选型提示官方原文强调只要工具链允许建议优先使用swagger-ui因为swagger-ui-dist会把更多代码通过网络传输到客户端Note: we suggest usingswagger-uiwhen your tooling makes it possible, asswagger-ui-distwill result in more code going across the wire.。swagger-ui-reactReact 组件封装第三个模块swagger-ui-react以 React 组件形式封装 Swagger UI适合 React 应用直接以SwaggerUI /组件方式使用其组件实现在仓库的 flavors/swagger-ui-react/index.jsx 中。安装命令$ npm install swagger-ui-react具体 props 与用法以该模块随附的 README 为准。Docker一条命令部署 Swagger UI官方维护了预构建的 Docker 镜像可直接从docker.swagger.io拉取。快速启动docker pull docker.swagger.io/swaggerapi/swagger-ui docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui该命令会启动一个 nginx 容器在宿主机的 80 端口对外提供 Swagger UI容器内部端口为 8080。挂载本地的 swagger.json把宿主机上的 OpenAPI 定义文件挂载进容器并通过SWAGGER_JSON环境变量指定容器内路径docker run -p 80:8080 -e SWAGGER_JSON/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui其中-v /bar:/foo把宿主机的/bar目录挂载为容器内的/fooSWAGGER_JSON指向该挂载点下的定义文件。指定外部 URL 的定义文件也可以不挂载文件而是让 Swagger UI 直接加载外部主机的 JSONdocker run -p 80:8080 -e SWAGGER_JSON_URLhttps://petstore3.swagger.io/api/v3/openapi.json docker.swagger.io/swaggerapi/swagger-ui修改应用根路径BASE_URL默认情况下应用部署在/。通过BASE_URL环境变量可以改变 Web 应用的根路径docker run -p 80:8080 -e BASE_URL/swagger -e SWAGGER_JSON/foo/swagger.json -v /bar:/foo docker.swagger.io/swaggerapi/swagger-ui这样 Swagger UI 将从/swagger路径对外提供服务而非/。自定义监听端口PORT 与 PORT_IPV6容器对外nginx 监听的端口默认为8080可用PORT覆盖IPv6 端口默认不启用可用PORT_IPV6单独指定docker run -p 80:80 -e PORT80 docker.swagger.io/swaggerapi/swagger-uidocker run -p 80:80 -e PORT_IPV68080 docker.swagger.io/swaggerapi/swagger-ui控制页面是否可被嵌入EMBEDDINGEMBEDDING变量用于允许/禁止 Swagger UI 通过 X-Frame-Options 被其他页面 iframe 嵌入默认禁止嵌入docker run -p 80:80 -e EMBEDDINGtrue docker.swagger.io/swaggerapi/swagger-ui镜像环境变量的仓库源码佐证以上环境变量的默认值全部定义在仓库根目录的 Dockerfile 中ENV API_KEY**None** \ SWAGGER_JSON/app/swagger.json \ PORT8080 \ PORT_IPV6 \ BASE_URL/ \ SWAGGER_JSON_URL \ CORStrue \ EMBEDDINGfalse可以看到除文档提到的变量外镜像还内置了API_KEY、CORS等开关CORStrue默认开启跨域支持。启动时这些变量的实际生效逻辑在 docker/docker-entrypoint.d/40-swagger-ui.sh 中实现例如存在SWAGGER_JSON_URL时用sed把初始化脚本swagger-initializer.js中默认的https://petstore.swagger.io/v2/swagger.json替换为目标 URL存在SWAGGER_JSON文件时以符号链接方式挂到 nginx 根目录并把初始化脚本中的默认 URL 替换为相对路径同时配合BASE_URL改写 nginx 的重写规则PORT_IPV6非空时向 nginx 配置追加listen [::]:${PORT_IPV6}EMBEDDING不为false时清空embedding.conf模板以允许嵌入。理解这份脚本有助于排查“为什么环境变量没生效”之类的问题。更完整的 Docker 配置入口除了上述专用变量Docker 镜像还支持用环境变量覆盖 Swagger UI 的大多数配置项字符串、布尔、数字、数组、对象五种类型均支持例如FILTERmyFilterValue、DEEP_LINKINGfalse、URLS[ { url: \...\, name: \...\ } ]、SPEC{ \openapi\: \3.0.4\ }详细规则见 Configuration 文档的 Docker 章节。如需编写 docker-compose 编排可参考同文档的Docker-Compose小节SUPPORTED_SUBMIT_METHODS[get, post]等.env文件的编码写法。unpkg在 HTML 中直接嵌入 Swagger UI如果你的页面不想引入任何构建工具可以直接通过 unpkg CDN 引用swagger-ui-dist的产物。最基础的用法是引用swagger-ui.css与swagger-ui-bundle.js后者是包含运行全部所需代码的单文件构建!DOCTYPE html html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / meta namedescription contentSwaggerUI / titleSwaggerUI/title link relstylesheet hrefhttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui.css / /head body div idswagger-ui/div script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-bundle.js crossorigin/script script window.onload () { window.ui SwaggerUIBundle({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, }); }; /script /body /html引入 StandalonePreset 增强 UI使用StandalonePreset即独立预设会额外渲染TopBar顶部搜索栏和ValidatorBadge在线校验徽标!DOCTYPE html html langen head meta charsetutf-8 / meta nameviewport contentwidthdevice-width, initial-scale1 / meta namedescription contentSwaggerUI / titleSwaggerUI/title link relstylesheet hrefhttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui.css / /head body div idswagger-ui/div script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-bundle.js crossorigin/script script srchttps://unpkg.com/swagger-ui-dist5.11.0/swagger-ui-standalone-preset.js crossorigin/script script window.onload () { window.ui SwaggerUIBundle({ url: https://petstore3.swagger.io/api/v3/openapi.json, dom_id: #swagger-ui, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], layout: StandaloneLayout, }); }; /script /body /html这里SwaggerUIBundle.presets.apis提供解析与渲染 OpenAPI 定义的核心能力SwaggerUIStandalonePreset提供独立部署的完整界面layout: StandaloneLayout指定使用独立布局。这与上一节swagger-ui-dist在 Node 中require出来的配置结构完全一致只是加载方式从模块系统换成了script标签。静态文件方式无 HTTP 服务器托管官方文档还提供了一种完全脱离 HTTP/HTML 的用法一旦 Swagger UI 成功构建出/dist目录你可以把它直接拷贝到自己的文件系统中由任意静态文件服务器托管。这里提到的/dist是仓库构建产物目录——构建脚本见 package.jsonnpm run build会依次构建样式表与各类 bundle构建完成后 dist 目录中包含swagger-ui-bundle.js、swagger-ui.css、swagger-ui-standalone-preset.js以及oauth2-redirect.html等关键资产。纯 HTML/CSS/JS 独立部署Standalone无需 npm如果目标环境如静态网站、CMS完全没有 npm最直接的方式是使用官方发布的 Standalone 产物下载 最新 release 的version字段将/dist目录中的内容复制到你的服务器用文本编辑器打开swagger-initializer.js把其中的https://petstore.swagger.io/v2/swagger.json替换为你自己的 OpenAPI 3.0 规范文件 URL。swagger-initializer.js是容器镜像与 Standalone 部署共用的初始化入口参见 docker/docker-entrypoint.d/40-swagger-ui.sh 中对它的sed替换逻辑它负责在页面加载时调用SwaggerUIBundle并注入你的定义地址。仓库的 dev-helpers/index.html 亦展示了类似的本地开发页结构可作为参考。结语如何选择安装方式综合以上四类渠道可以按以下规则快速决策前端工程有 Webpack/Rollup 等打包器→ 选swagger-ui并按需引入dist/swagger-ui.css与oauth2-redirect.html参考 Webpack Getting Started 示例Node 服务端需要托管静态页面→ 选swagger-ui-dist用absolutePath()拿到安装路径后交给express.static等中间件容器化 / 快速部署→ 拉取docker.swagger.io/swaggerapi/swagger-ui镜像配合SWAGGER_JSON、SWAGGER_JSON_URL、BASE_URL、PORT、PORT_IPV6、EMBEDDING等环境变量完成定制纯 HTML 页面 / 无构建环境→ 用 unpkg CDN 引入swagger-ui-bundle.js或下载 release 产物把/dist拷贝到服务器并编辑swagger-initializer.js。无论选择哪条路径初始化配置的核心都是SwaggerUI({ url / spec, dom_id, presets, layout })这一套对象结构掌握它即可在所有场景间平滑迁移。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考