Swagger UI 项目全览基于 OpenAPI 规范的交互式 API 文档工具生态【免费下载链接】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 是一套由 HTML、JavaScript 与 CSS 组成的开源资源集合它能够根据 OpenAPI旧称 Swagger规范文件自动生成可视化、可交互的 API 文档让后端开发者与最终消费方无需查看任何实现代码即可浏览并调用 API 资源。本文以仓库 README.md 为主线结合仓库源码梳理其三大 npm 分发模块的定位与差异、OpenAPI 版本兼容矩阵、匿名安装统计机制、文档导航体系、Cypress 集成测试方案以及当前已知问题帮助你快速判断在何种场景下选用哪种接入方式并理解其底层工程结构。项目简介从规范文件到交互式文档Swagger UI 的核心价值在于“自动生成”它读取一份符合 OpenAPI2.0 及 3.x规范的描述文件将其渲染为可直接浏览与试用的交互式页面。团队成员或最终消费者可以在页面上查看每个端点的路径、方法、参数、请求体与响应结构甚至直接点击“Try it out”向真实后端发起请求从而在前后端分离的开发流程中充当文档展示与联调入口。从仓库源码结构看这一能力由 src/core/index.js 中导出的SwaggerUI(userOptions)构造函数承载它依次合并查询参数、运行时参数与用户传入选项见 src/core/config/defaults.js 中的defaultOptions随后通过插件系统System注册各类功能插件并渲染到指定的 DOM 节点。整个渲染管线由 src/index.js 统一导出是三个 npm 模块共同的逻辑内核。三个 npm 模块定位与选型本仓库向 npm 发布三个不同的模块三者共享同一套核心代码但面向不同的工程场景模块适用场景核心特征swagger-ui能够解析 npm 依赖的 SPA 项目Webpack、Browserify、Rollup 等传统 npm 模块主文件直接导出 Swagger UI 主函数swagger-ui-dist服务端项目或无法解析 npm 模块依赖的 SPA无依赖模块内含运行所需的全部静态资源swagger-ui-reactReact 应用以 React 组件形式封装 Swagger UI官方建议如果你在构建单页应用优先使用swagger-ui而非swagger-ui-dist因为后者体量显著更大文档原文明确提示 “swagger-ui-distis significantly larger”会带来更多网络传输开销。swagger-ui面向模块打包器的常规入口swagger-ui模块的主文件导出主函数并附带命名空间样式文件swagger-ui/dist/swagger-ui.css。安装与使用方式如下npm install swagger-uiimport SwaggerUI from swagger-ui // 或使用 require const SwaggerUI require(swagger-ui) SwaggerUI({ dom_id: #myDomId })在 package.json 中可以看到该模块的入口映射浏览器环境import对应./dist/swagger-ui-es-bundle-core.jsrequire对应./dist/swagger-ui.jsNode 环境则映射到swagger-ui-bundle.js与swagger-ui-es-bundle.js。SwaggerUI函数支持通过dom_idCSS 选择器或domNodeDOM 节点引用指定渲染容器二者在 src/core/index.js 的render函数中被统一处理。更完整的工程化接入示例可参考 docs/samples/webpack-getting-started仓库内包含webpack.config.js、src/index.js与src/swagger-config.yaml等完整样例。swagger-ui-dist服务端直出的无依赖方案swagger-ui-dist面向需要把静态资源直接下发给浏览器的服务端项目。模块内容与仓库中的dist目录保持一致其中最常用的是swagger-ui-bundle.js——它将 Swagger UI 运行所需的全部代码打包进单个文件。模块还提供index.html资源方便直接静态托管。导入该模块后会得到一个absolutePath辅助函数返回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)在 swagger-ui-dist-package/index.js 的源码中可以看到该模块同时导出了SwaggerUIBundle与SwaggerUIStandalonePreset且absolutePath与getAbsoluteFSPath两个名称指向同一实现历史原因两者都被保留避免破坏已有用户代码。因此无法处理传统 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完全等价。layout: StandaloneLayout配合SwaggerUIStandalonePreset会额外渲染顶栏TopBar与在线校验徽章其实现位于 src/standalone/presets/standalone/index.js由 TopBar、Configs、StandaloneLayout 与 SafeRender 四个插件组合而成。如果你只需要纯粹的 HTML/JS/CSS可以直接下载最新 release把/dist目录内容复制到服务器即可完全不需要 npm。swagger-ui-reactReact 组件封装swagger-ui-react把 Swagger UI 打包成 React 组件供 React 应用直接使用npm install swagger-ui-react其实现位于 flavors/swagger-ui-react/index.jsx组件内部通过useEffect在挂载时创建SwaggerUIConstructor实例并将spec、url、docExpansion、deepLinking、filter等几十个 props 逐项透传给底层构造器同时借助usePrevious与useEffect监听url/spec变化在属性更新时调用specActions.download(url)或specActions.updateSpec(...)实现动态刷新。组件的propTypes还完整声明了docExpansionlist/full/none、supportedSubmitMethodsget、put、post、delete、options、head、patch、trace、defaultModelRenderingexample/model等参数约束可作为 React 场景下的参数速查表。OpenAPI 规范兼容性矩阵OpenAPI 规范自 2010 年诞生以来经历了 5 次主要修订Swagger UI 与 OpenAPI 规范的兼容关系如下来自 README.mdSwagger UI 版本发布日期OpenAPI 规范兼容性说明5.32.02026-02-272.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2, 3.2.0tag v5.32.05.19.02025-02-172.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1, 3.1.2tag v5.19.05.0.02023-06-122.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.1.0tag v5.0.04.0.02021-11-032.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3tag v4.0.03.18.32018-08-032.0, 3.0.0, 3.0.1, 3.0.2, 3.0.3tag v3.18.33.0.212017-07-262.0tag v3.0.212.2.102017-01-041.1, 1.2, 2.0tag v2.2.102.1.52016-07-201.1, 1.2, 2.0tag v2.1.52.0.242014-09-121.1, 1.2tag v2.0.241.0.132013-03-081.1, 1.2tag v1.0.131.0.12011-10-111.0, 1.1tag v1.0.1从仓库源码看对 OpenAPI 3.0/3.1/3.2 的差异化支持是通过独立插件实现的src/core/plugins/oas3、src/core/plugins/oas31 与 src/core/plugins/oas32 分别承载对应版本的组件覆盖与选择器扩展并在 src/core/index.js 中随默认预设一起注册。需要旧版 2.x 行为的读者仓库另有2.x分支可供参考。匿名安装统计Scarf与退出机制Swagger UI 通过 Scarf 收集匿名安装统计数据这些数据用于支持库维护者仅在安装阶段运行README 明确注明 “ONLY run during installation”。该依赖在 package.json 中以scarf/scarf: 1.4.0固定版本引入。退出统计有两种方式任选其一方式一在项目package.json中关闭// package.json { // ... scarfSettings: { enabled: false } // ... }方式二设置环境变量SCARF_ANALYTICSfalse npm install即在安装 npm 包的环境中设置SCARF_ANALYTICSfalse即可。此外在仓库自身的 package.json 的allowScripts字段中可以看到scarf/scarf: false表明本仓库在构建自身时也停用了该脚本。文档导航体系仓库围绕 Swagger UI 的完整生命周期维护了体系化的文档本节统一换算为仓库根目录相对路径便于按需深入使用Usage安装指南涵盖 npm、Docker、unpkg、静态文件四种分发渠道配置指南全部配置项说明含 Docker 环境变量详解CORS 说明OAuth2 接入Deep Linking 深链接局限性说明版本检测自定义Customization自定义总览插件 API自定义布局开发Development环境搭建脚本说明贡献Contributing遵循通用的 CONTRIBUTING 指南位于组织级仓库中。Docker 部署环境变量速览在 docs/usage/installation.md 的 Docker 小节中可以快速拉起官方镜像镜像托管于 docker.swagger.iodocker pull docker.swagger.io/swaggerapi/swagger-ui docker run -p 80:8080 docker.swagger.io/swaggerapi/swagger-ui该命令以 nginx 为宿主、在 80 端口对外提供 Swagger UI。常用环境变量包括环境变量作用示例SWAGGER_JSON挂载宿主机上的 swagger.json 文件-e SWAGGER_JSON/foo/swagger.json -v /bar:/fooSWAGGER_JSON_URL指向外部主机上的 OpenAPI 文档 URL-e SWAGGER_JSON_URLhttps://petstore3.swagger.io/api/v3/openapi.jsonBASE_URL修改 Web 应用的基础路径默认/-e BASE_URL/swagger此时页面在/swagger提供PORT应用监听端口默认8080-e PORT80PORT_IPV6IPv6 监听端口默认不启用-e PORT_IPV68080EMBEDDING是否允许被 iframe 嵌入默认禁用控制X-Frame-Options-e EMBEDDINGtrueCORS是否启用跨域响应头-e CORStrue这些变量的落地逻辑可从 docker/docker-entrypoint.d/40-swagger-ui.sh 窥见启动时由 Node 配置器生成swagger-initializer.js随后根据SWAGGER_JSON_URL/SWAGGER_JSON用sed替换其中的占位 URL、根据BASE_URL改写 nginx 重写规则、根据PORT_IPV6追加 IPv6 监听并依据EMBEDDING/CORS开关清空对应的 nginx 模板片段见 docker/embedding.conf 与 docker/cors.conf最终对 html/js/css 做 gzip 预压缩。nginx 服务模板位于 docker/default.conf.template。集成测试基于 Cypress 的端到端方案仓库的端到端测试基于 Cypress覆盖深链接、OAuth2 各授权流程、OAS 3.0/3.1/3.2 特性、插件渲染、安全场景等大量场景。运行完整套件本地npm run cy:ci——该命令会自动启动所需服务器、以无头模式运行 Cypress结束后关闭服务器。注意测试期间不要占用相同端口运行开发服务器mock 接口默认运行在 3204 端口见 package.json 中cy:mock-api的定义。交互式调试单个用例npm run cy:dev会打开 Cypress runner 可视化界面。无头模式运行单个 spec一个终端启动服务器另一个终端执行npm run cy:start # 在第二个终端 npm run cy:run -- --spec test/e2e-cypress/e2e/features/deep-linking.cy.jscy:ci的内部实现是start-server-and-test cy:start http://localhost:3204 cy:run——先并行拉起cy:serverwebpack dev server与cy:mock-apijson-server 提供 mock 数据数据文件为 test/e2e-selenium/db.json等待 3204 端口就绪后再执行 Cypress。单元测试则通过 Jest 独立运行npm run test:unit配置见 config/jest/jest.unit.config.js。浏览器支持Swagger UI 支持最新版本的 Chrome、Safari、Firefox 与 Edge 浏览器。这一支持目标也体现在构建配置中webpack 构建通过BROWSERSLIST_ENV环境变量区分browser-development/browser-production/isomorphic-production等目标环境见 package.json 中的 build 脚本由 browserslist 配置决定最终的转译与 polyfill 范围。已知问题3.X以下为 3.X 系列当前已知的问题清单该清单会持续更新且不包含旧版本中本就不存在的功能参数支持仅覆盖原先支持范围的一部分JSON 表单编辑器JSON Form Editor尚未实现对collectionFormat的支持不完整国际化l10n/翻译尚未实现外部文件的相对路径支持尚未实现。理解这些问题有助于在集成时评估功能边界例如涉及collectionFormat的参数序列化或依赖 i18n 的多语言文档场景需要自行确认当前版本的实际情况。安全联系与开源许可安全问题上报请通过邮件 securityswagger.io 私下披露安全相关的问题或漏洞而不要使用公开的 issue 跟踪器。仓库同时配有 SECURITY.md 文档供参考。开源许可Swagger UI 采用 Apache 2.0 许可并附带一份 NOTICE 文件其中包含额外的法律声明与信息。仓库根目录的 composer.json 表明其同样支持通过 ComposerPHP生态引入该资源包。小结通过本文你可以确认三件事其一swagger-ui模块打包器、swagger-ui-dist服务端/免依赖与swagger-ui-reactReact三大模块各自适用什么工程形态以及它们共享的SwaggerUI构造内核与配置默认值src/core/config/defaults.js其二当前 5.x 系列已覆盖 OpenAPI 2.0 到 3.2 的全谱系规范具体到某一版本可对照兼容矩阵其三从安装统计退出、Docker 环境变量到 Cypress 测试命令仓库提供了完整的工程化配套。若需要进一步深入配置项细节可直接从 docs/usage/configuration.md 与 docs/customization/overview.md 继续阅读。【免费下载链接】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），仅供参考