本文来自网易云社区。
作者：盛国存
背景
我们日常在使用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+款云产品！
更多网易研发、产品、运营经验分享请访问网易云社区。
相关文章：
【推荐】 数据迁移的应用场景与解决方案Hamal
【推荐】 数据分析中，用户行为分析最重要的3个点
【推荐】 聊聊WS-Federation