yaml - Converting Swagger specification JSON to HTML documentation

Question

For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation, I used this editor to generate some for now.

I saved the JSON and YAML files created using that editor, and now I need to create the final interactive Swagger documentation (this statement might sound naive and vague).

Can someone please let me know how I can convert the Swagger JSON specification file to actual Swagger documentation?

I am on the Windows platform and do not know anything about Ant/Maven.

score 81 · Accepted Answer

尝试使用redoc-cli。

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

然后我发现redoc-cli非常好用，输出真的很赞，一个漂亮的 index.html文件。

安装：

npm install -g redoc-cli

用法：

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

score 48 · Accepted Answer

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

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

score 25 · Accepted Answer

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

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

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

score 19 · Accepted Answer

看看漂亮的赃物

它有

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

我在看 Swagger Editor 并认为它可以导出预览窗格，但事实证明它不能。所以我写了我自己的版本。

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

score 19 · Accepted Answer

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

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

score 16 · Accepted Answer

请参阅 GitHub 上的swagger-api/swagger-codegen项目；项目 README 展示了如何使用它来生成静态 HTML。请参阅生成静态 html api 文档。

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

score 8 · Accepted Answer

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

const ui = SwaggerUIBundle({
    url: ...,

进入

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

score 6 · Accepted Answer

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

score 2 · Accepted Answer

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

下载phar文件https://github.com/zircote/swagger-php/blob/master/swagger.phar
安装作曲家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 的路径

如果您需要其他帮助，请随时询问。

score 2 · Accepted Answer

有一个小型Java 程序可以从 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。

score 2 · Accepted Answer

2

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

于 2021-11-23T06:29:35.110 回答

yaml - Converting Swagger specification JSON to HTML documentation

11 回答 11

Related

Reference