ApiDoc 一键生成注释

本文来自网易云社区。

作者：盛国存

背景

我们日常在使用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+款云产品！

更多网易研发、产品、运营经验分享请访问网易云社区。

相关文章：
【推荐】 Apache流框架Flink，SparkStreaming，Storm对比分析（二）
【推荐】 Clojure基础课程2-Clojure中的数据长啥样?