logo标签列表

如何从Swagger文档生成静态HTML文件？

linuxswaggerapi-dochtml-generation
27

我使用一个yaml文件创建了一个Swagger文档，该文件位于：

api/swagger/swagger.yaml

现在我想分享一个静态 HTML 文档及其定义，但在 Swagger 项目 上已经声明，他们不打算支持 HTML 的生成。

如何从 Swagger 项目生成一个静态 HTML 文件？

7个回答
25

我能想到的最简单的方法是使用Swagger编辑器：

  1. 前往：https://editor.swagger.io
  2. 点击顶部菜单栏中的“文件”，然后选择“导入文件”
  3. 导入后，在顶部菜单栏中点击“生成客户端”，然后选择“HTML”或“HTML2”以生成静态HTML文档

editor.swagger.io使用generator.swagger.io生成API客户端、服务器存根和文档，而generator.swagger.io则由开源项目Swagger Codegen提供支持。

生成的 HTML/HTML2 文档在处理 GET 查询参数方面表现得相当糟糕... - Haroldo_OK
那个链接上支持的最新版本是3.0。这是个问题，因为我的API生成的是3.1的模式。但是在那个页面上，他们链接到了支持3.1的新版本。这是链接：https://editor-next.swagger.io - undefined
14
  1. 下载https://github.com/swagger-api/swagger-ui - 需要的文件夹是 "dist"
  2. 将你的Swagger JSON复制到dist文件夹中
  3. 打开index.html并将底部标签内的URL值更改为./swagger.json（或者你的Swagger JSON文件名）（参见这里）
  4. 上线吧！（或启动本地服务器查看输出）
4

有一个swagger2markup-cli可以生成静态adoc文件。

请确保您已安装Java运行时环境。（我使用的是Java(TM) SE Runtime Environment (build 1.8.0_111-b14)）。

您可以获取jar包：

wget https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/1.1.0/swagger2markup-cli-1.1.0.jar

您可以通过以下方式生成一个静态的adoc文件:

java -jar ~/your/path/swagger2markup-cli-1.1.0.jar convert  -i api/swagger/swagger.yaml --outputFile static-swagger

那个adoc文件可以通过asciidoctor转换成一个html文件：
asciidoctor *.adoc

你可能需要安装它，因为我正在使用Ubuntu，我可以通过以下方式进行安装：

sudo apt-get -qq install asciidoctor
这个解决方案对我有效，只有几点需要注意：生成的页面没有超链接，它们只是简单的HTML页面，没有框架。asciidoctor依赖于Ruby。 - Michal Špondr
2
0
另一个答案建议使用Swagger Editor，这很好。但是，要获取一个单独的文件导入到其中：
  1. npm install -g @apidevtools/swagger-cli
  2. swagger-cli bundle openapi.yaml --outfile ./openapi-expanded.json --type json
上述命令假定您的根文件名为openapi.yaml，并且您想要一个输出JSON文件openapi-expanded.json：该JSON文件就是您要导入的文件。
0
使用类似这样的HTML文件来加载您的OpenAPI定义：
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css">

  <title>Your App API v1</title>

<body>

  <div id="your-app-docs" />

  <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
  <script>

    window.onload = function () {

      const ui = SwaggerUIBundle({
        url: "openapi.yml",
        dom_id: "#your-app-docs",
        deepLinking: true,
      })

    }

  </script>

</body>

</html>

然后您可以将其本地托管，或使用Netlify等服务将其托管在Web上。

0
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接