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

Question

正在查看 the documentation for installing Swagger-UI one can see that two official npm modules are being published: swagger-ui and swagger-ui-dist. However, I really struggle to figure out how these are supposed to be used with an already existing OpenApi 3.0 规范。

我唯一需要的是一个简单的 Web 应用程序（纯 node.js 或 express.js 或任何有效的东西），它将为我现有的 specification.yml 嵌入到纯 Swagger 中的文档提供服务-UI 路径上的文件，如 /docs.

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

我最接近的是下载 a release tar ball，解压 dist 文件夹，使用 sed 之类的工具将默认规范文件替换为我自己的规范文件，最后将其托管在像 nginx.

这样的网络服务器

然而，这对我来说看起来不必要的复杂，让我想知道 npm 模块应该用于什么。

Answer 1

如果您正在寻找任何可行的方法，最简单的解决方案是使用现有的 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 调整为 ui 满足您的需求

Answer 2

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

使用 unpkg

unpkg is an automated content delivery network 用于在 npm 注册表中发布的所有模块。它允许在静态 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 and webpack 是来自 npm 生态系统的模块打包器，可以收集 npm 模块及其所有依赖项，然后将它们打包到一个 js 文件中。然后可以在 HTML 页面中加载和使用此文件。

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

首先，全局安装browserify：

npm install -g browserify

然后，在当前文件夹中本地安装 swagger-ui 模块：

npm install --save swagger-ui

最后，将 swagger-ui 模块及其所有依赖项打包到一个输出文件中：

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

根据 HTML 包含它的页面可能如下所示：

<!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 或 webpack 执行其他任务，则可能首选此方法。

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

How to use the swagger-ui npm module with an existing OpenAPI specification file

node.js

npm

swagger

swagger-ui

openapi

使用 unpkg

使用 browserify / webpack