首页 文章

将Swagger规范JSON转换为HTML文档

提问于
浏览 次
51

对于一些用PHP编写的REST API，我被要求创建Swagger文档，因为我不知道为这些现有API添加注释和创建这样的文档的任何简单方法，我现在使用this editor生成一些 .

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

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

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

yaml swagger swagger-php

9 回答

  • 14

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

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

    回复于
  • 7

    参见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应用程序 .

    回复于
  • 6

    尝试使用 redoc-cli .

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

    然后我发现redoc-cli非常容易使用，输出真的是2真棒，一个 single and beautiful index.html 文件 .

    Installation ：

    npm install -g redoc-cli

    Usage ：

    redoc-cli bundle -o index.html swagger.json
    回复于
  • 2

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

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

    成

    const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

    回复于
  • 0

    有一个小Java program，它从yaml文件生成docs（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 .

    回复于
  • 29

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

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

    回复于
  • 11

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

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

    回复于
  • 8

    一切都太困难或记录不好，所以我用一个简单的脚本swagger-yaml-to-html.py来解决这个问题

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

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

    回复于
  • 4

    看看pretty-swag

    它有

    • 类似于Swagger-Editor的右侧面板

    • 搜索/过滤

    • 架构折叠

    • 实时反馈

    • 输出为单个html文件

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

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

    回复于

相关问题