Question

对于一些用PHP编写的REST API，我被要求创建Swagger文档，由于我不知道为这些现有API添加注释和创建这样的文档的任何简单方法，我使用{{ 3}}暂时生成一些。

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

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

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

Answer 1

我在寻找工具时对swagger-codegen不满意，所以我写了自己的。看看bootprint-swagger

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

Answer 2

查看pretty-swag

它有

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

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

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

Answer 3

尝试使用 redoc-cli 。

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

然后我发现redoc-cli非常易于使用，并且输出确实很棒-2，这是一个美观的index.html 文件。

安装：

npm install -g redoc-cli

用法：

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

Answer 4

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

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

Answer 5

所有内容都太难或太难记录，所以我用一个简单的脚本swagger-yaml-to-html.py来解决这个问题，这样就像这样工作

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

这适用于YAML，但修改它以使用JSON也是微不足道的。

Answer 6

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

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

到

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

Answer 7

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

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

Answer 8

点击此链接：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 / library
克隆swagger-ui / library
为API创建资源和模型php类
执行PHP文件以生成json
在api-doc.json中提供json的路径
在swagger-ui dist文件夹中的index.php中给出api-doc.json的路径

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

Answer 9

我发现称为api-html的工具非常有用。它会生成一个很棒的html5 UI，其中有很多可能性。

有用于生成online或通过cli tool的选项。

以下是在“ api-html”上进行演示的链接：pets-demo

Answer 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。

Answer 11

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

将Swagger规范JSON转换为HTML文档

11 个答案: