swagger-ui - SwaggerUIBundle 和 SwaggerUi 有什么区别

Question

我已经在我找到的样本中看到了这两种情况，但还没有看到它们有什么不同。如果您仅在 HTML 页面中使用它(不使用单页应用程序)是否需要捆绑包，或者如果您使用的是单页应用程序，是否需要使用捆绑包？

Swagger UI docs讨论两种部署 swagger-ui 的方法。

traditional npm -swagger-ui

dependency-free module -swagger-ui-dist

我看过例子 like this one其中 SwaggerUIBundle 用于似乎托管在 tomcat(python 或其他一些 Web 服务器)示例中的网页。

<script src="./swagger-ui-bundle.js"> </script>
// later
<script>
window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",

但也见过 examples like this一个使用 SwaggerUi 的。

window.swaggerUi = new SwaggerUi({
  url: "http://petstore.swagger.wordnik.com/api/api-docs",
  dom_id: "swagger-ui-container",

搜索返回如下内容:

swagger-ui-bundle.js - https://github.com/swagger-api/swagger-ui/issues/3978

SwaggerUi - https://stackoverflow.com/a/29497301/3281336

SwaggerUIBundle - https://github.com/swagger-api/swagger-ui/wiki/FAQ

Answer 1

本页Installation Distribution Channels NPM Registry说:

SwaggerUIBundle is equivalent to SwaggerUI.

但随后解释了差异。因此，它们在功能上是等效的，但您选择的将取决于您的网络服务器/网站如何为 swagger 用户界面页面提供服务。
const ui = SwaggerUIBundle(... 的第一个示例适用于 Swagger UI 3.x，即 Swagger UI 的当前版本。 window.swaggerUi = new SwaggerUi(... 的第二个示例适用于旧的 Swagger UI 2.x。信用 @Helen在 this 中获取此信息回答)

有关更多详细信息，请阅读...

SwaggerUI 解释

SwaggerUI 用于可以导入 npm 模块的应用程序。 这包括 React、Angular 或其他单页应用程序 (SPA)，它们包含类似 webpack 的工具来打包资源以交付给浏览器。

该网页是这样说的:
import SwaggerUI from 'swagger-ui'

swagger-ui is meant for consumption by JavaScript web projects that include module bundlers, such as Webpack, Browserify, and Rollup.

这是使用 npm 安装模块 swagger-ui 的示例.

import SwaggerUI from 'swagger-ui'
// or use require, if you prefer
const SwaggerUI = require('swagger-ui')
SwaggerUI({
  dom_id: '#myDomId'
})

SwaggerUIBundle 解释

当您的应用程序不支持导入 npm 模块(例如，java webapp)时，使用 SwaggerUIBundle。

可以使用 加载 Swagger 用户界面招摇 index.html 页面 (包含在 swagger-ui-bundle 中)或您自己的包含捆绑文件并使用如下所示 Javascript 的个人 html 页面:

以下内容来自网站，经过编辑以突出我的上述陈述:

The [...] dist folder [has] swagger-ui-bundle.js, which is a build of Swagger-UI that includes all the code it needs to run in one file. The folder also has an index.html asset, to make it easy to serve Swagger-UI...

如何使用 SwaggerUIBundle 的示例是:

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 示例令人困惑

它令人困惑，因为它说:

if you're in a JavaScript project that can't handle a traditional npm module, you could do something like this:

var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

它使用 的 require()是一个 npm 模块 包含捆绑包的方式。

解释这一点的一种不那么令人困惑的方式是:

如果您在非模块环境中使用 Swagger，那么您需要以某种方式将 swagger 包 javascript 加载到浏览器页面中，然后使用如下所示的 SwaggerUIBundle 使 swagger 用户界面在指定的 dom_id 处呈现(在下面的示例中它是 swagger-ui )。

const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  })

将 swagger-ui-bundle 加载到页面的方式取决于您使用的技术。如果您愿意，可以使用 <script src="bundle.js"></script>. 加载页面见 https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html (在 swagger-ui/dist/index.html 中)。

如果您在 NodeJS express 应用程序中，您可以使用以下命令将 swagger 包加载到页面上:

var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

如何将 swagger bundle javscript 放到页面上取决于您。