作者:拍友2702938227 | 来源:互联网 | 2023-09-25 19:15
本文来自网易云社区。
作者:盛国存
背景
我们日常在使用ApiDoc维护管理api文档,提高了api文档的整体维护性。但在老旧接口中,补充接口注解无疑是一次繁重的体力劳动。仔细查看,大多数接口的格式 其实是相似的,那么,是否可以将体力活做的技术一些?
答案是sure,只需要三步。分析log,构建接口数据,生成APIDoc。
过程阐述
下面以个人开发机器下的某个测试接口为例,阐述整个过程:
在实际的业务中可能存在这样的日志(前提是所有的业务日志都是通过同一套标准进行输出的)
重点看红框标注的部分。依次为,日志等级、logId、uri、arrRequest/action tpl data。仔细分析,我们会发现,TRACE模式即为请求,包含所有请求信息。DEBUG模式即为响应,包含所有响应信息。具体数据结构不做赘述。
以此为例,根据日志模式、logId、uri、arrRequest、tpl data 等信息可以构建标准的接口请求&返回信息。
需要注意的是:
1、单个日志中可能会存在日志的多个请求,所以要对分析后的日志做数据过滤;
2、如果接口返回数据中存在list,要对list做单一化处理(否则后续的生成的apidoc会存在大量重复字段);
3、日志读取尽量使用yield(要不大文件会扛不住的);
处理逻辑就不描述了,so easy。
那么添加一个新的apidoc的步骤现在变为:
a、从log.dt解析接口的请求&返回数据;
b、提取uri、method、requestparam、retData等字段;
c、根据接口uri每个接口只留取一个请求实例;
d、遍历接口返回数据的结构,list数组中只留取一个item实例;
e、根据apidoc的格式拼装数据,按照uri生成独立文件;
f、剪贴至action,并完成字段注释等操作;
其中a-e的操作 可以概述为 打开浏览器器(1s)→刷业务页面(10s)→执行脚本(1s)→复制粘贴(1s)→补充字段注释信息(xxxs)
只需要一个简单的命令
ApiDoc就写好了
再执行一下 apidoc -i xxxx -o xxxx 就大功告成了
总结
现实开发的过程中,存在着很多重复琐碎的事情,比如维护繁琐的文档,每更新一次代码都需要执行一次apidoc命令,有时候会经常忘记,我们可以搞一个crontab检测文件夹是否有过改动,有的话就自动执行一次命令,一年可以省下不少时间哩……^_^,日常还有很多类似的事,可以开发一些小工具将偷懒发挥到极致。
网易云免费体验馆,0成本体验20+款云产品!
更多网易研发、产品、运营经验分享请访问网易云社区。
相关文章:【推荐】 四六级成绩查询,你的『验证码』刷出来了吗?【推荐】 在Android中使用Protocol Buffers(下篇)