logo标签列表

将Swagger规范的JSON转换为HTML文档

yamlswaggerswagger-php
124

有些用PHP编写的REST API，我被要求创建Swagger文档。由于我不知道如何注释这些现有的API并创建这样的文档，因此我使用了这个编辑器来生成一些。

我保存了使用该编辑器创建的JSON和YAML文件，现在我需要从中创建“交互式”Swagger文档。

请问有人能告诉我如何将Swagger JSON规范文件转换为实际的Swagger文档吗？

我使用Windows平台，不了解Ant/Maven。

我尝试使用Swagger UI，但它无法渲染我的JSON。唯一显示的警告是：“此API正在使用已弃用的Swagger版本！请访问http://github.com/wordnik/swagger-core/wiki获取更多信息”。 - Salil
13个回答
117

2023年5月17日更新

看起来redoc-cli已被弃用，所以请使用https://www.npmjs.com/package/@redocly/cli替代。[来源：@Dave]

尝试使用redoc-cli。

我之前使用的是bootprint-openapi，通过它我生成了一堆文件（bundle.js、bundle.js.map、index.html、main.css和main.css.map），然后可以使用html-inline将其转换成一个单独的.html文件，生成一个简单的index.html文件。

然后我发现 redoc-cli 很容易使用，输出效果非常棒，只有一个漂亮的 index.html 文件。

安装：

npm install -g redoc-cli

用法:

redoc-cli bundle -o index.html swagger.json
13
这个工具产生的输出结果是所有提到的工具中最美丽的。 - Jakub Moravec
4
直接使用可执行文件名并不总是有效的，通过 npx redoc-cli ... 执行更加可靠。 - Crouching Kitten
1
哇，我花了不到一分钟就把所有的文档都放在一个文件里了 - 在 Mac 上；现在 npm 是内置的吗？谢谢！ - Josef Habr
4
小更新：现在 redoc-cli 要求您使用 build 选项而不是 bundle。 - TheDiveO
3
尝试过这个，但它告诉我已经被弃用了，建议使用 https://www.npmjs.com/package/@redocly/cli 代替。 - Dave
显示剩余3条评论
48

在寻找工具进行此操作时，我并不满意 swagger-codegen，因此我自己写了一个工具。请查看 bootprint-swagger

与 swagger-codegen 相比的主要目标是提供简单的设置（但您需要使用 nodejs）。并且应该很容易适应自己的需求，这是 bootprint 项目的核心功能。

12
警告：截至2016年11月，bootprint-swagger的作者似乎已经放弃了这个项目。swagger-codegen仍然得到很好的支持。 - Brent Matzelle
26
我是作者，文本内容如下：“很抱歉我不能在近期内为这个项目开发新功能。但是：我可能会能够讨论和合并拉取请求，并发布新版本。”你可能会称之为被放弃了，但我会称之为“暂停”。我还将邀请任何有兴趣为该项目做出贡献的人参与进来。 - Nils Knappmeier
1
发现 spectacle 从 Swagger JSON 生成的文档看起来更好看。 - eternalthinker
注意：正在查看此线程的用户们请注意，SPECTACLE已经无法使用了。npm安装会导致错误。 - bbh
35

所有的东西都太难或文档写得很糟糕，所以我用了一个简单的脚本swagger-yaml-to-html.py来解决这个问题，它的工作方式如下：

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

这是为YAML准备的，但将其修改为与JSON兼容也很容易。

现在也可以作为Docker使用了！https://github.com/yousan/swagger-yaml-to-html - noamtm
28

我花了很多时间尝试了很多不同的解决方案 - 最终我是用这种方法做到的:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>
你只需要在相同位置提供path/to/my/swagger.yaml（或使用CORS标头）。
1
太棒了，谢谢！我已经使用了以下代码：<link rel="stylesheet" href="https://petstore.swagger.io/swagger-ui.css"> <script src="https://petstore.swagger.io/swagger-ui-bundle.js"></script> - Erando
1
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui.css"> <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.11.1/swagger-ui-bundle.js"></script> - Mateusz Będziński
19

请查看pretty-swag

它有：

  1. 与Swagger-Editor的右侧面板相似的外观
  2. 搜索/筛选
  3. 模式折叠
  4. 实时反馈
  5. 输出为单个html文件

我在查看Swagger Editor时发现它无法导出预览窗格，所以我编写了自己的版本。

免责声明：本工具作者就是我。

1
我发现pretty-swag是一个直接而理想的工具，具有适当的CLI和API入口点。 我唯一的抱怨（也是迫使我处理swagger-ui复杂性的抱怨）是它未能正确处理对象组合/扩展。文档中任何使用allOf的地方都会产生undefined，即使在最简单的情况下（“合并”单个对象，相当于根本不使用allOf）。 - HonoredMule
3
我刚刚为你推出了“allOf”功能，请查看。 - TLJ
2
似乎不支持Swagger/OpenAPI V3。 - SeinopSys
16
在GitHub上查看swagger-api/swagger-codegen项目；该项目的README展示了如何使用它生成静态HTML。请参见生成静态HTML API文档。
如果您想查看swagger.json，可以安装Swagger UI并运行它。您只需将其部署到Web服务器上（从GitHub克隆存储库后的dist文件夹），然后在浏览器中查看Swagger UI。这是一个JavaScript应用程序。
谢谢。我的问题是swagger-ui不接受2.0规范。然而，这似乎是最简单的答案，所以我会暂时接受它。 - Salil
Swagger工具仍在不断发展2.0版本。然而，我发现Swagger UI可以用于我的以"swagger": "2.0"开头的文件。 - djb
此外，从 Swagger 编辑器中，您可以导出 JSON 规范（而不是 YAML），Swagger UI 应该能够读取它。（注意：swagger.json 必须位于与 Swagger UI 应用程序相同的主机/端口上，或者您必须启用 CORS；请参阅 GitHub 上 Swagger 编辑器中的 README.md。） - djb
10
您可以从以下链接下载Swagger UI：https://github.com/swagger-api/swagger-ui，下载dist文件夹后，修改index.html文件，更改构造函数即可。
const ui = SwaggerUIBundle({
    url: ...,

进入

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

现在dist文件夹包含了你所需的一切内容，并且可以直接分发。
这种方法对我来说最容易。 - Tiber Septim
7

对于Swagger API 3.0版本，从在线Swagger编辑器生成Html2客户端代码对我来说效果很好！

其他的建议对我都没有用，但是这个有效。这是最简单的解决方案，而且效果非常好。应该是得到最多赞的答案。 - Stephen Oller
你是指这个吗？https://editor.swagger.io/? - surfmuggle
4

Redocly的CLI界面具有从OpenAPI规范文件构建HTML文档的工具。

sudo npm i -g @redocly/cli
redocly build-docs my-swagger.yml -o docs.html
redoc-cli已被弃用，现在更名为redocly。 - Kita
2
1
有没有在线编辑器（除了swagger-editor）可以为我生成这个？如果有更简单的方法，我不想注释我的PHP API。问题是，我已经发现swagger-editor生成swagger规范v2.0，而swagger-ui目前无法处理它。 - Salil
@Salil 我知道的是Swagger提供了自己的在线编辑器，即http://editor.swagger.wordnik.com/。我不知道其他的在线编辑器，如果你发现了，请与我们分享，谢谢 :) - Syed Raza Mehdi
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接