代码先行，使用Avantation和Swagger UI自动化生成API文档

vfuns

已于 2024-06-12 22:59:02 修改

阅读量235

点赞数 3

分类专栏： OpenAPI 文章标签： ui 自动化运维

于 2024-06-12 15:47:04 首次发布

本文链接：https://blog.csdn.net/weixin_42338765/article/details/139628650

版权

OpenAPI 专栏收录该内容

1 篇文章 0 订阅

订阅专栏

在现代软件开发中，API文档是确保开发者能够正确、高效地使用API的关键。OpenAPI规范提供了一种标准化的方式来描述RESTful API，而Swagger UI则是一个流行的工具，用于以用户友好的方式展示这些文档。本文将介绍如何使用Avantation工具从HTTP存档（HAR）文件生成OpenAPI规范的YAML文件，并通过Swagger UI来展示这些文档。

步骤1：使用Avantation生成OpenAPI YAML文件

Avantation是一个工具，可以从HAR文件生成OpenAPI 3.0规范。HAR文件是一种JSON格式的文件，用于记录浏览器与服务器之间的HTTP交互。

首先，你需要安装Avantation。如果你已经安装了Node.js，可以通过npm来安装Avantation：

npm install -g avantation

然后，你可以使用Avantation来处理HAR文件并生成OpenAPI规范的YAML文件：

avantation path/to/your/harfile.har -o path/to/output/openapi.yaml

这个命令会读取HAR文件，并根据其中的HTTP请求生成OpenAPI规范，然后将结果保存到指定的YAML文件中。

步骤2：创建index.html加载OpenAPI.yaml

一旦你有了OpenAPI规范的YAML文件，下一步就是使用Swagger UI来展示这些规范。首先，你需要下载Swagger UI的发行版。你可以从Swagger UI的GitHub仓库中获取：

https://github.com/swagger-api/swagger-ui/releases

下载并解压Swagger UI后，找到index.html文件。你需要编辑这个文件，让它指向你的OpenAPI YAML文件。找到index.html中的以下脚本并进行修改

HTML代码

<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="https://your-web-site/public/swagger-ui/swagger-ui.css" >
    <link rel="icon" type="image/png" href="https:///your-web-site/public/images/swagger_icon.png" sizes="16x16" />
    <link rel="stylesheet" type="text/css" href="https:///your-web-site/public/css/swagger_doc.css">
    <style>
      html
      {
        box-sizing: border-box;
        overflow: -moz-scrollbars-vertical;
        overflow-y: scroll;
      }

      *,
      *:before,
      *:after
      {
        box-sizing: inherit;
      }

      body
      {
        margin:0;
        background: #fafafa;
      }
    </style>
  </head>

  <body>
    <div style="border-bottom: 2px solid rgba(0,0,0,.15); background-color:#ffffff">
        <div class="swagger-header-div">
            <table style='width: 98%'>
                <tr>
                <td><img class="header-img" src="/public/images/swagger_icon.png"></img><p class="header-title"><strong></strong></p></td>
                <td style='width:82%; text-align:right'><iframe id='rd'></iframe></td>
                </tr>
            </table>
        </div>
    </div>
    <div id="swagger-ui"></div>

    <script src="https:///your-web-site/public/swagger-ui/swagger-ui-bundle.js"> </script>
    <script src="https:///your-web-site/public/swagger-ui/swagger-ui-standalone-preset.js"> </script>
    <script src="https:///your-web-site/public/js/swagger_doc.js"> </script>
    <script>
    const DisableTryItOutPlugin = function () {
          return {
          statePlugins: {
            spec: {
                wrapSelectors: {
                 allowTryItOutFor: () => () => false
                 }
                }
            }
        }

    }

    window.onload = function() {
        select_option_onload();
      // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
        url: "openapi.yaml",
        validatorUrl: null,
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl //,
          // DisableTryItOutPlugin,
        ],
        layout: "StandaloneLayout",
        tryItOutEnabled: true,
        requestInterceptor: (request) => {
          request.rejectUnauthorized = false;
          return request;
        }

      })
      // End Swagger UI call region
      window.ui = ui
    }
  </script>
  </body>
</html>

确保将url参数的值替换为你的OpenAPI YAML文件的实际路径。

步骤3：使用Python的SimpleHTTPServer发布网页

由于直接从文件系统访问HTML文件在某些浏览器中受到限制，你需要通过一个本地服务器来提供Swagger UI页面。Python的SimpleHTTPServer是一个简单的选择。在包含index.html的目录中运行以下命令：

# Python 2.x version
python -m SimpleHTTPServer 8000

# Python 3.x version
python3 -m http.server 8000

这将在端口8000上启动一个HTTP服务器，然后你可以通过浏览器访问来查看你的API文档。

结论

通过结合使用Avantation和Swagger UI，你可以轻松地从HTTP请求日志中生成并展示OpenAPI文档。这个过程不仅节省了手动编写文档的时间，而且还可以确保文档的准确性和最新性。对于需要快速迭代和发布API的团队来说，这种自动化方法是一个巨大的时间节省者。

vfuns

关注

3
点赞
踩
4

收藏

觉得还不错? 一键收藏
打赏
0
评论
代码先行，使用Avantation和Swagger UI自动化生成API文档

在现代软件开发中，API文档是确保开发者能够正确、高效地使用API的关键。OpenAPI规范提供了一种标准化的方式来描述RESTful API，而Swagger UI则是一个流行的工具，用于以用户友好的方式展示这些文档。本文将介绍如何使用Avantation工具从HTTP存档（HAR）文件生成OpenAPI规范的YAML文件，并通过Swagger UI来展示这些文档。
复制链接

扫一扫