在没有任何连接的情况下在 Flask 上显示 Swagger UI

Question

有人知道我可以在 flask 上提供 swagger UI .yml 文件而无需创建或连接 API 的方法吗？我只是想在网站上展示 swagger 文件，以便人们可以看到如何使用 API，但我不想创建 API 或连接任何东西，因为 API是私有的，因此无论如何都无法调用。

API 来自 AWS API 网关，所以我不能用 flask 连接任何东西。

我调查了 connexion，但我需要连接我的 API 方法来使用它，但它不起作用。

我可以使用 openapi 编辑器将 api 规范转换为 html 然后提供 html 但我想尝试使用漂亮的布局swagger ui 提供。

Answer 1

您可以使用 Swagger UI npm package，它发布了一个 JavaScript 包，您可以将其与规范文档一起提供。

您可能需要通过将规范文件加载到 UI 对象来做一些小的操作。

编辑

当我做完全相同的事情时，我找到了一些代码。我创建了一个 JavaScript 文件，该文件将从服务器加载规范并使用 SwaggerUI 包显示它，替换指定的 HTML 标记。这也利用一个库将 YAML 解析为 JSON.

我使用 webpack 来捆绑所有东西，但您可以使用其他网络捆绑器。

JavaScript: index.js

const jsYAML = require('js-yaml');
const SwaggerUI = require('swagger-ui');

function httpGetAsync(url, callback) {
    let xmlHttp = new XMLHttpRequest();

    xmlHttp.onreadystatechange = function () {
        if (xmlHttp.readyState === 4 && xmlHttp.status === 200)
            callback(xmlHttp.responseText);
    };

    xmlHttp.open("GET", url, true);
    xmlHttp.send(null);
}

function parseYamlSpec(yaml) {
    try {
        return jsYAML.safeLoad(yaml);
    } catch (error) {
        console.error('Error parsing OpenAPI YAML to JavaScript object');
        console.error(error);
        return null;
    }
}

function displayOpenApiSpec() {
    httpGetAsync('./openapi.yaml', function (yamlSpec) {
        SwaggerUI({
            dom_id: '#openapi',
            spec: parseYamlSpec(yamlSpec)
        })
    });
}

displayOpenApiSpec();

HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Swagger Doc</title>
    <link rel="stylesheet" type="text/css" href="swagger-ui.css"/>
</head>
<body>
    <div id="openapi"></div>
    <script src="bundle.js"></script>
</body>
</html>

我还从 SwaggerUI 包中获取了 CSS 文件并提供了它。这是使它看起来漂亮且实用的必要条件。

编辑 2

package.json

{
  "name": "sdk",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "build": "webpack"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "js-yaml": "^3.12.0",
    "swagger-ui": "^3.20.2"
  },
  "devDependencies": {
    "webpack": "^4.27.1",
    "webpack-cli": "^3.1.2"
  }
}

webpack.config.js

const path = require('path');

module.exports = {
    entry: './index.js',
    output: {
        path: path.resolve(__dirname),
        filename: 'bundle.js'
    }
};

鉴于您已安装 Node.js and npm，您可以使用上述 package.json 和 webpack.config.js 文件，以及运行从工作目录中使用以下两个命令：

npm install
npm build

这是在做什么

本质上，您想要提供一个 HTML 文件、一个 JavaScript 包和一个 CSS 样式表，用于将您的 Swagger 规范加载到 DOM , 设计得很好，并使用 SwaggerUI 库使其具有交互性。

对于给定的 JavaScript 文件，这在浏览器中不起作用，因为它使用 Node.js 样式 require 来导入两个需要的库。但是 webpack 将能够用实际的 JavaScript 内联库和 "minify" 代码替换它们，以便它的文件大小更小。

为此，您需要安装所有这些库（使用 npm、节点包管理器）以及 webpack（及其命令行界面），然后运行 webpack 这样它会为你打包所有东西。

package.json 文件列出了所有需要的库和 webpack，并定义了一个 "script" 供您使用运行 webpack 命令。通过运行ning npm install，npm 将为您在名为 node_modules.

的本地文件夹中安装所有内容

然后，运行ning npm build、Node.js 将执行 webpack 命令，该命令将执行所有捆绑并创建输出文件 bundle.js (上面的 HTML 文件中引用了它）。

完成后，你可以添加index.html、bundle.js、swagger-ui.css（我从SwaggerUI目录中复制到node_modules)，以及您在服务器上公开提供的文件的 Swagger 规范。

Answer 2

Swagger 在项目的 dist folder 中有一个已发布的示例。

浏览器就绪 javascript 捆绑包 available in unpkg or directly via cloudflare CDN 可以直接从那里提供。

在您的用例中，您可以在 dist 文件夹中编写类似于 index.html 文件的模板文件，而无需为 Swagger UI 包设置额外的构建过程你的烧瓶项目。

您的模板将如下所示，您将 url 的值替换为包含 API 定义的 yaml 文件中的 URL：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js"></script>
    <!-- <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui-standalone-preset.js"></script> -->
    <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
    <!-- <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui-bundle.js"></script> -->
    <link rel="stylesheet" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css" />
    <!-- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.22.1/swagger-ui.css" /> -->
    <title>Swagger</title>
</head>
<body>
    <div id="swagger-ui"></div>
    <script>
        window.onload = function() {
          SwaggerUIBundle({
            url: "https://petstore.swagger.io/v2/swagger.yaml",
            dom_id: '#swagger-ui',
            presets: [
              SwaggerUIBundle.presets.apis,
              SwaggerUIStandalonePreset
            ],
            layout: "StandaloneLayout"
          })
        }
    </script>
</body>
</html>

在没有任何连接的情况下在 Flask 上显示 Swagger UI

Display Swagger UI on Flask without any hookups

python

flask

python-3.x

swagger-ui

aws-api-gateway

编辑

编辑 2

这是在做什么