Swagger UI 版本检测指南：从界面特征到控制台命令的完整辨识方案-二趣网

Swagger UI 版本检测指南：从界面特征到控制台命令的完整辨识方案

【免费下载链接】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 问题时，准确获知当前部署的版本号往往是定位问题、判断功能是否可用（例如深链接、OAuth 2.0 流程、OAS 3.1/3.2 支持）的第一步。本文基于 swagger-ui 官方文档 version-detection.md 编写，系统讲解如何先通过界面特征判断主版本（3.x 与 2.x），再通过浏览器控制台或源码注释获取精确版本号，并深入到versions插件与 Webpack 构建注入的源码实现，帮助你理解版本信息从构建到浏览器的完整链路。

为什么需要检测版本，以及正确的检测顺序

Swagger UI 在持续演进过程中，检测版本的方式本身发生了变化：3.x 版本在浏览器中暴露了结构化的版本对象，而 2.x 及更早版本则只能在打包产物头部注释中查找。因此文档给出的第一步是先确定主版本（major version），再按对应方法获取精确版本。

尤其需要注意的是：如果你的 Swagger UI 被深度定制过（样式、布局被大量修改），无法凭外观判断主版本，就需要同时尝试两种方法，看哪一种能得到结果，从而最终确认版本号。

视觉辨识 Swagger UI 3.x

官方为 3.x 版本提供了界面截图 docs/images/swagger-ui3.png，可以作为视觉参考：

Swagger UI 3.x 的几个显著辨识特征：

API 版本以徽章（badge）形式出现在标题旁边：这一徽章由 openapi-version.jsx 渲染，内容形如OAS 3.0、OAS 3.1，用于标明 OpenAPI 规范的版本（例如openapi: 3.1.0），而非 Swagger UI 自身的版本。
如果存在 schemes 或 authorizations，它们会显示在 operations 区域上方的一条横栏中。
"Try it out" 功能默认不开启，需要用户点击操作区的 "Try it out" 按钮才进入可执行状态。
所有响应码（response code）显示在参数之后。
operations 区域之后存在一个 Models（模型）区块，用于展示 schema 定义。

在浏览器控制台获取 3.x 精确版本

当确认是 3.x 后，获取精确版本的步骤如下：

打开浏览器开发者工具的 Web Console（不同浏览器入口不同）。
在控制台输入并执行：
```
JSON.stringify(versions)
```

返回结果形如：

swaggerUi : Object { version: "3.1.6", gitRevision: "g786cd47", gitDirty: true, … }

其中version字段即为精确版本号，上例对应3.1.6。

注意：versions全局对象的注入功能自3.0.8起才提供。如果执行该命令得不到结果，说明你使用的版本早于 3.0.8，此时首要动作是升级。

深入源码：`versions`对象从何而来

versions全局变量并非浏览器或 Swagger UI 页面模板自带的，而是由一个名为versions的插件在应用加载完成后注入的。插件定义见 src/core/plugins/versions/index.js，它只有一个afterLoad钩子：

import afterLoad from "./after-load.js" const VersionsPlugin = () => ({ afterLoad, }) export default VersionsPlugin

真正的注入逻辑在 src/core/plugins/versions/after-load.js：

import win from "core/window" const afterLoad = () => { const { GIT_DIRTY, GIT_COMMIT, PACKAGE_VERSION, BUILD_TIME } = buildInfo win.versions = win.versions || {} win.versions.swaggerUI = { version: PACKAGE_VERSION, gitRevision: GIT_COMMIT, gitDirty: GIT_DIRTY, buildTimestamp: BUILD_TIME, } }

可见控制台输出中的version、gitRevision、gitDirty分别对应PACKAGE_VERSION、GIT_COMMIT、GIT_DIRTY，此外还额外暴露了buildTimestamp构建时间。这也能解释文档示例输出末尾的省略号…——对象中还有未在示例中展开的字段。

而buildInfo这个在源码中被直接引用的"全局变量"，其实是构建期由 Webpack 的DefinePlugin注入的。在 webpack/_config-builder.js 中可以找到：

new webpack.DefinePlugin({ buildInfo: JSON.stringify({ PACKAGE_VERSION: process.env.REACT_APP_VERSION ?? pkg.version, GIT_COMMIT: gitInfo.hash, GIT_DIRTY: gitInfo.dirty, BUILD_TIME: new Date().toUTCString(), }), }),

从这段构建配置可以确认：

version（PACKAGE_VERSION）优先取环境变量REACT_APP_VERSION，未设置时回退到package.json的version字段；
gitRevision（GIT_COMMIT）来自当前 Git 仓库的提交哈希；
gitDirty（GIT_DIRTY）表示工作区相对该提交是否有未提交的改动，这正是控制台输出中gitDirty: true这类值的来源；
buildTimestamp（BUILD_TIME）是构建发生时的 UTC 时间字符串。

该插件被 src/core/index.js 与 src/core/presets/base/index.js 等入口引入，因此标准构建的 Swagger UI（包括swagger-ui-bundle.js）都具备这一能力。

补充说明：OAS 版本徽章 ≠ Swagger UI 版本

3.x 界面标题旁的徽章（如OAS 3.1）来自 openapi-version.jsx，它渲染的是所加载 API 文档的 OpenAPI 版本，与 Swagger UI 自身的版本是两个不同的概念。此外，Swagger UI 在解析文档时还会通过 version-pragma-filter.jsx 校验文档版本字段：仅支持swagger: "2.0"与openapi: 3.0.n（例如openapi: 3.0.4）；若同时出现swagger与openapi字段或缺失合法版本字段，会渲染对应的错误提示。这一点在通过界面排查"版本相关异常"时值得留意——它属于文档版本问题，而不是 UI 版本问题。

视觉辨识 Swagger UI 2.x 及更早版本

官方同时提供了 2.x 界面的截图 docs/images/swagger-ui2.png：

Swagger UI 2.x 的显著辨识特征：

API 版本显示在页面底部（而非标题旁的徽章）。
schemes 不会被渲染。
Authorization（授权）区域若被渲染，会出现在导航栏旁边，而不是 operations 上方的独立横栏。
"Try it out" 功能默认开启，与 3.x 的默认关闭行为相反。
成功的响应码显示在参数上方，其余响应码显示在参数下方，而非像 3.x 那样统一排在参数之后。
operations 区域之后没有 Models 区块。

在打包产物注释中获取 2.x 精确版本

2.x 及更早版本没有versions全局对象，需要通过以下方式获取精确版本：

找到 Swagger UI 的源码文件：既可以是本机磁盘上的安装目录，也可以在浏览器中通过"查看网页源代码"（View Page Source）功能定位。
找到并打开swagger-ui.js。

文件顶部有一段 banner 注释，其中包含精确版本号，形如：

/** * swagger-ui - Swagger UI is a dependency-free collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API * @version v2.2.9 * @license Apache-2.0 */

上例中的版本号即为2.2.9。

其他可辅助确认版本的途径

除上述官方文档指定的两种方法外，结合仓库现状，还可以通过以下途径交叉验证（适用前提各有不同）：

查看依赖清单：若通过 npm 安装，可查看package.json或package-lock.json中swagger-ui、swagger-ui-dist或swagger-ui-react的版本声明，这对应安装方式可参考 docs/usage/installation.md。
Docker 部署：若通过 Docker 镜像部署，容器镜像标签即对应版本，构建与运行配置可参考 docker/default.conf.template 与 docker/docker-entrypoint.d/40-swagger-ui.sh。
自行构建：从源码构建时，版本号由 webpack/_config-builder.js 中pkg.version决定，并可通过REACT_APP_VERSION环境变量覆盖——理解这一点后，在排查"为什么控制台显示的版本与预期不符"时会很有帮助（例如发布流程在构建期覆盖了版本）。

小结与决策流程

可以将整个检测过程归纳为一条清晰的决策链：

观察界面布局，确定主版本：看标题旁是否有OAS徽章、响应码位置、Models 区块是否存在等特征；
若为 3.x（且不早于 3.0.8）：在浏览器控制台执行JSON.stringify(versions)，读取swaggerUi.version；
若为 2.x 及更早：打开swagger-ui.js源码，读取头部 banner 注释中的@version；
若界面被深度定制无法判断：两种方法都尝试一遍，以能取得结果者为准；
若控制台命令不可用且源码注释中也找不到版本信息：极可能版本过老，建议直接升级到当前发布版本。

掌握这一套检测方法，无论面对官方原版还是被高度定制过的部署，你都能快速、准确地定位 Swagger UI 的精确版本，为后续的升级规划、功能排查与 Bug 报告提供可靠依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析