Question

看the documentation for installing Swagger-UI，可以看到两个正式的npm模块正在发布：swagger-ui和swagger-ui-dist。但是，我真的很难弄清楚应该如何将它们与已经存在的OpenApi 3.0规范一起使用。

我唯一需要的是一个简单的Web应用程序（普通node.js或express.js或其他可行的工具），它将为嵌入在Swagger-UI文件中的现有specification.yml文档提供服务像/docs这样的路径。

由于需要以可重复的方式进行操作（最终将在Docker容器中运行），因此在此过程中不需要手动编辑文件。

我能得到的最接近的是下载a release tar ball，解压缩dist文件夹，使用sed之类的工具将默认的规范文件替换为我自己的文件，并最终将其托管在网络服务器上像nginx。

但是，这对我来说似乎不必要，很复杂，让我想知道npm模块应该用于什么目的。

Answer 1

最后，我找到了实现问题中概述的目标的两种方法。

使用unpkg

unpkg是针对npm注册表中发布的所有模块的自动content delivery network。它允许在静态HTML文件中包含和使用任何npm模块，而无需任何复杂的包管理器，依赖项解析器等。如果您不需要使用npm生态系统，则特别有用直。

对于swagger-ui，这样的HTML文件如下所示。请注意，我们正在导入swagger-ui-dist程序包，该程序包已经包括所有必需的依赖项。

<!DOCTYPE html>
<!--Inspired by https://gist.github.com/buzztaiki/e243ccc3203f96777e2e8141d4993664-->
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css" >
  </head>

  <body>
    <div id="swagger-ui"></div>
    <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"> </script>
    <script type="text/javascript">
      window.onload = function() {
        // Swagger-ui configuration goes here.
        // See further: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
        SwaggerUIBundle({
          deepLinking: true,
          dom_id: '#swagger-ui',
          showExtensions: true,
          showCommonExtensions: true,
          url: specification.json // <-- adjust this to your webserver's structure
        });
      };
    </script>
  </body>
</html>

将此HTML文件托管在您的网络服务器上，一切都解决了。

使用browserify / webpack

browserify和webpack是npm生态系统中的模块捆绑器，可以收集npm模块及其所有依赖项，然后将它们捆绑成一个{{1 }}文件。然后可以将该文件加载到HTML页面中并使用。

尽管这两种工具的细节可能在功能方面有所不同，但是对于这项工作，它们两者的工作方式几乎相同。以下示例使用js，但是使用browserify的一般方法是相同的。

首先，全局安装webpack：

browserify

然后，在当前文件夹中本地安装npm install -g browserify模块：

swagger-ui

最后，将npm install --save swagger-ui模块及其所有依赖项捆绑到一个输出文件中：

swagger-ui

包含它的相应HTML页面可能如下所示：

browserify --require swagger-ui -o bundle.js

如果您仍将生态系统内的<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="./node_modules/swagger-ui/dist/swagger-ui.css"> <title>Swagger-UI</title> </head> <body> <div id="swagger-ui"></div> </body> <script type="text/javascript" src="./bundle.js"></script> <script type="text/javascript"> window.onload = function() { // Swagger-ui configuration goes here. // See further: https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md SwaggerUI({ deepLinking: true, dom_id: '#swagger-ui', showExtensions: true, showCommonExtensions: true, url: specification.json // <-- adjust this to your webserver's structure }); }; </script> </html>或browserify用于其他任务，则可能更喜欢这种方法。

Answer 2

如果您正在寻找可行的方法，最简单的解决方案是使用现有的swagger-ui（如演示商店）并在url参数中传递您的规范：
http://petstore.swagger.io/?url=https://raw.githack.com/heldersepu/hs-scripts/master/swagger/4411/7.json

如果您想要更多的独立解决方案，请将swagger-ui dist目录复制到您的部署中：
https://github.com/swagger-api/swagger-ui/tree/master/dist
然后调整index.html以适合您的需求

如何将swagger-ui npm模块与现有的OpenAPI规范文件一起使用

2 个答案:

使用unpkg

使用browserify / webpack