写代码,哪个程序员都不害怕。 写文档,哪个程序员都害怕! 为什么? 还不是因为 API 工具不好使,不便捷,同步麻烦,测试看不懂……
今天这次我们深度“盘”一下 Eolink 这款免费 API 协作平台,围绕【智能生成+盘活 API 资产】这一功能上,到底投入了多大的开发成本,给我们带来了多少惊喜! 本文重点围绕以下产研需求展开(文末有福利)。
当然在正式开始对接 Eolink 前,咱需要先使用 Python Flask 框架在本地构建一个微型项目,用于写接口代码。
一、Eolink 准备工作,Python 快速搭建 Swagger我选用的 Web API 框架是 Flask,所以搭建 Swagger 需要用到 Flasgger 模块,如果你用 FastAPI,可以不用多走这一步,直接使用 FastAPI 原生 API 文档即可。 使用 Flasgger 得到一个 Swagger UI 具体步骤,不做重点描述,咱们的目标是打通 Swagger 和 Eolink,让 API 研发资产可以盘活,Swagger 简易部署流程请参考下述步骤。 首先安装 flasgger 模块。 pip install flasgger 然后新建 main.py 文件,同时输入如下代码(本地 Python 版本为 3.8),代码有点长,可以跳过阅读,直接复制代码到本地相应文件中。
使用 python main.py 运行 Flask 项目,然后访问 http://127.0.0.1:5000/apidocs/,在浏览器得到如下视图,如果此时你获得界面与我一直,那么恭喜你,准备工作已经完成,后续我们需要对上述代码进行修改,目的是在 Eolink 每次 自动生成 API 文档 之后,对比差异。
在上述界面中,找到 appispec_1.json 超链接位置,点击该链接,页面跳转到 Swagger 生成的 JSON 文件地址,如下所示。 http://127.0.0.1:5000/apispec_1.json 在浏览器中直接打开该 URL 地址,得到如下 JSON 格式的数据,下图为部分内容展示。 二、Eolink 通过 Swagger 文件,自动生成 API 文档在前文拿到 JSON 文件地址后,就可以在 Eolink API 研发管理平台读取该网络文件,并自动生成API文档页面了,具体操作如下。 进入 API 管理控制台具体项目中,在左侧菜单栏找到【其它】,然后选择【API文档生成】。
进入到 【自动生成API文档】功能页之后,选择【添加来源】按钮。 在弹窗中选择通过 Swagger URL 生成 API 文档,点击下一步: 在【添加来源】弹窗输入 Swagger 生成的 JSON 文件地址,就是刚刚得到的 JSON 文件地址,这里一定要注意,该地址能通过外网访问(因为 Eolink 服务器不能调用我们本地的数据),并且为 JSON 格式(刚刚已经核对过目标数据),然后参考下图进行填写。 上传前文获取的 JSON 文件到临时服务器,修改 Swagger.json 文件地址,点击确定,完成配置。
点击确定,完成来源配置,配置页面自动关闭,出现如下列表。 点击同步按钮,将 Swagger 文件内容同步到 Eolink 中。 再次切换到 API 列表页面,可以看到 API 同步之后的效果。 此时打开 任意API 文档,可以查看到 API 描述,请求地址,请求参数,返回参数等其它信息,到这里 Eolink 已经成功进行同步。
这里咱们需要做一个小小的总结,在公司团队协作的场景下,经常出现文档和代码不同步情况,所以我们引入了 Swagger 模块,让小组中的程序员,在编写代码的同时,只需要更新自己的代码和注释,即可自动生成 API 文档。 但 Swagger 只是一个用于生成、描述和调用 RESTful 接口的 Web 服务,它远远无法满足团队中对于API 的所有诉求,而 Eolink 在软件研发整个生命周期中,做了全方位的补充,从而 盘活 API 研发资产。 除了手动点击【同步】操作外,我们还可以通过 Open API 实现自动同步。 三、Eolink 通过 Open API 触发同步操作本篇博客中使用的是 Open API V2 版本,在正式编写代码前,需要先在工作空间管理后台获取调用密钥。 密钥配置 点击在管理后台右上角头像位置的【账号设置】,进入工作空间设置菜单。 切换的页面中,选择 【Open API】,进入密钥配置。
解析来我们查看一下 通过 Open API 触发同步操作的请求说明。
有了这些标准之后,我们可以快速通过 Python 编写一个自动触发同步操作的脚本,代码如下。
在运行代码前,先对前文的 Python Flask 接口代码进行一下修改,增加【用户来源】字段。然后使用上面的 3 行代码,即可实现自动化同步。上述代码运行结果如下所示。 {'type':'api','status':'success'} 阅读到这里,我们已经实现了【通过 Open API 触发同步操作】,你可以将代码部署到云服务器,并设置成自动任务,这样 Eolink 就可以实时的抓取服务端 API 文档,解放你的双手了。 四、Eolink 基于 IDEA 插件上传 APIEolink 除了手动同步和以Open API 形式同步文档以外,还可以通过 IDEA 插件实现快速在研发工具上操作并上传API接口文档,而且比Swagger的方式还快,具体步骤如下所示。 打开 IDEA 插件,再插件市场搜索 Eolink ApiKit。 点击上图的 Install 即可安装。 接下来就需要对该插件进行配置,参照下图找到 Eolink Settings。 看一下 Eolink Settings 中的相关参数配置。
然后在你的项目源码空白处,点击树表右键,选择 Generate Class Doc,一键生成全部 API 注释文档。 生成完毕,再次选择 Upload All Api 即可上传所有 API 注释到目标服务器,真正的一键生成文档,一键上传文档,如果你恰好使用的是 IDEA ,一定要尝试一下该方式,在 Eolink 的帮助下,写文档会变成一件非常轻松的事。 五、基于 Eolink API 文档智能生成请求代码和业务代码前文我们做的所有工作,都是为了让现有 API 文档快速生成并同步到 Eolink 中,只有这样,我们才能体验 Eolink 这个一站式 API 生产力工具,盘活 API 研发资产时的强大。 下面将借助刚刚建立的接口,为大家展示 Eolink API 智能生成请求代码和业务代码这一重点功能,过程中还将为大家介绍 Eolink 的一些小细节亮点。
选择进入前文同步的任意接口中,可以得到该接口的详细描述,更多内容可在你的 Eolink 后台查看,这里仅展示局部。 如果你善于发现,一定会发现一个非常不起眼的按钮 ---【生成预览数据】,点击它。这个操作非常适合测试工程师进行数据模拟,尤其是当 API 接口包含大量参数待填写时,可以大幅度节约手写参数的消耗时间,而且测试的时候,可以避免使用 abc,aaa,1111,123,这些 “左手乱敲” 的输入数据。 |
|