将 Swagger 规范 JSON 转换为 HTML 文档

Posted

技术标签:

【中文标题】将 Swagger 规范 JSON 转换为 HTML 文档【英文标题】：Converting Swagger specification JSON to HTML documentation 【发布时间】：2014-11-06 04:08:42 【问题描述】：

对于一些用 php 编写的 REST API，我被要求创建 Swagger 文档，由于我不知道有任何简单的方法可以向这些现有 API 添加注释并创建这样的文档，所以我使用了 this editor暂时生成一些。

我保存了使用该编辑器创建的 JSON 和 YAML 文件，现在我需要创建最终的交互式 Swagger 文档（这种说法可能听起来幼稚和含糊）。

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

我在Windows平台，对Ant/Maven一无所知。

【问题讨论】：

我试过 [github.com/wordnik/swagger-ui](Swagger UI) 但它没有呈现我的 json。显示的唯一警告是“此 API 正在使用已弃用的 Swagger 版本！请参阅github.com/wordnik/swagger-core/wiki 了解更多信息”。 【参考方案1】：

尝试使用 redoc-cli。

我使用bootprint-openapi 生成一堆文件（bundle.js、bundle.js.map、index.html、main.css 和main.css.map），然后您可以将其转换为单个@987654329 @file 使用html-inline 生成一个简单的index.html 文件。

然后我发现redoc-cli 非常好用，输出非常棒，单一而漂亮的 index.html 文件。

安装：

npm install -g redoc-cli

用法：

redoc-cli bundle -o index.html swagger.json

【讨论】：

这个工具确实是所有提到的工具中最漂亮的输出。 生成的一体化HTML文件很大。在从自定义 HTML 进行实时渲染的情况下，JS 库依赖项 (~800KB) 也是如此。有谁知道如何减小尺寸？ 这是迄今为止最好的 imo，而且由于我们是为使用桌面的开发人员构建的，因此输出大小不是问题。 使用直接可执行名称并不总是有效，npx redoc-cli ... 执行更可靠。 哇。我花了不到一分钟的时间将所有文档放在一个文件中 - 在 Mac 上； npm 现在是内置的吗？谢谢！【参考方案2】：

当我在寻找一个工具来做到这一点时，我对swagger-codegen 不满意，所以我自己写了一个。看看bootprint-swagger

与swagger-codegen 相比，主要目标是提供简单的设置（尽管您需要nodejs）。 并且应该很容易根据自己的需要调整样式和模板，这是bootprint-project 的核心功能

【讨论】：

警告：自 2016 年 11 月起，bootprint-swagger 的作者显然已经放弃了该项目。 swagger-codegen 仍然得到很好的支持。 我是作者，文字说：“很抱歉，我在不久的将来无法为这个项目开发新功能。但是：我可能会讨论和合并拉取请求，并发布新版本。”你可以称之为放弃，我称之为“搁置”。我还将邀请任何有兴趣为该项目做出贡献的人。 发现 spectacle 从 swagger JSON 中生成了更好看的文档【参考方案3】：

一切都太难或记录不充分，所以我用一个简单的脚本 swagger-yaml-to-html.py 解决了这个问题，就像这样

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

这适用于 YAML，但修改它以使用 JSON 也很简单。

【讨论】：

现在也可以作为 docker 使用！ github.com/yousan/swagger-yaml-to-html 这是优雅的方式，对我有用【参考方案4】：

查看pretty-swag

有

    类似于Swagger-Editor 的右侧面板 搜索/过滤 架构折叠 实时反馈 输出为单个 html 文件

我正在查看 Swagger Editor，并认为它可以导出预览窗格，但结果却不能。所以我写了我自己的版本。

完全披露：我是该工具的作者。

【讨论】：

我发现 pretty-swag 是一个简单而理想的工具，具有适当的 CLI 和 API 入口点。我唯一的抱怨（也是迫使我处理 swagger-ui 的复杂性的抱怨）是它未能正确处理对象组合/扩展。在文档中任何使用allOf 都会产生undefined，即使在最简单的情况下（“合并”单个对象，相当于根本不使用allOf）。 刚刚为您推出了allOf 功能。看看吧。 似乎不支持 Swagger/OpenAPI V3【参考方案5】：

我花了很多时间，尝试了很多不同的解决方案——最后我是这样做的：

<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 标头）

【讨论】：

太棒了，谢谢！我用过 petstore.swagger.io/swagger-ui.css"> 【参考方案6】：

参见 GitHub 上的 swagger-api/swagger-codegen 项目；项目 README 展示了如何使用它来生成静态 HTML。见Generating static html api documentation。

如果您想查看 swagger.json，您可以install the Swagger UI 并运行它。您只需将其部署在 Web 服务器上（从 GitHub 克隆存储库后的 dist 文件夹）并在浏览器中查看 Swagger UI。这是一个 javascript 应用程序。

【讨论】：

谢谢。我的问题是 swagger-ui 不接受 2.0 规范。但是，这看起来是最简单的答案，所以我会接受这个（暂时）。 Swagger 工具仍在为 2.0 发展。但是，我发现 Swagger UI 确实适用于以“swagger”开头的 2.0 文件：“2.0”， 此外，您可以从 Swagger 编辑器导出 JSON 规范（不是 YAML，而是 JSON），Swagger UI 应该能够读取它。 （注意：swagger.json 必须与 Swagger UI 应用位于同一主机/端口上，否则您必须启用 CORS；请参阅 GitHub 上 Swagger 编辑器中的 README.md【参考方案7】：

你也可以从https://github.com/swagger-api/swagger-ui下载swagger ui， 取 dist 文件夹，修改 index.html： 改变构造函数

const ui = SwaggerUIBundle(
    url: ...,

进入

const ui = SwaggerUIBundle(
    spec: YOUR_JSON,

现在 dist 文件夹包含您需要的所有内容，并且可以按原样分发

【讨论】：

这种方法对我来说最简单。【参考方案8】：

对于 Swagger API 3.0，从在线 Swagger 编辑器生成 Html2 客户端代码非常适合我！

【讨论】：

没有其他建议对我有用，但这个有用。这是最简单的解决方案，效果很好。应该是最受好评的答案。【参考方案9】：

看看这个链接：http://zircote.com/swagger-php/installation.html

    下载phar文件https://github.com/zircote/swagger-php/blob/master/swagger.phar 安装 Composer https://getcomposer.org/download/ 制作composer.json 克隆 swagger-php/库 克隆 swagger-ui/库 为 API 创建资源和模型 php 类 执行PHP文件生成json 在 api-doc.json 中给出 json 的路径 在 swagger-ui dist 文件夹中的 index.php 中给出 api-doc.json 的路径

如果您需要其他帮助，请随时提出。

【讨论】：

是否有在线编辑器（除了 swagger-editor）可以为我生成这个？如果有更简单的方法，我不想注释我的 PHP API。我发现问题是 swagger-editor 生成 swagger spec v2.0，而 swagger-ui 目前还没有处理这个问题。 @Salil 我只知道 swagger 提供了它自己的在线编辑器，即editor.swagger.wordnik.com 我不知道有任何其他在线编辑器，如果您发现任何与我们分享，谢谢： )【参考方案10】：

有一个小的 Java program 从 yaml 文件生成文档（adoc 或 md）。

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

很遗憾，它只支持OpenAPI 2.0，不支持OpenAPI 3.0。

【讨论】：

【参考方案11】：

如果你在 Gitlab 中提交你的 JSON 文件，它会为你呈现它。

【讨论】：

哇，听起来不错。希望他们能在 7 年零 2 个月前做到这一点 :-)

以上是关于将 Swagger 规范 JSON 转换为 HTML 文档的主要内容，如果未能解决你的问题，请参考以下文章

将 Swagger JSON 转换为 RAML/YAML

如何将swagger JSON对象转换为Java类对象

Swagger.json 到 xslt 转换器

“nestjs/swagger”中的哪个函数将 DTO 转换为 Swagger 模型定义？

Swagger：将 Java LocalDateTime 转换为 Joda LocalDateTime

无法将 swagger JSON 或 YAML 导入 Postman