在使用apidoc之前,我一直使用wiki来写文档,后来发现这种方式更新起来比较痛苦,时间一长甚至就忘记了更新了。一直在寻找能够使用注释直接生成文档的程序。某一天同事推荐了apidoc,发现这正是我想要的工具。
apidoc原理
apidoc的原理是扫描你的代码文件,提取出注释部分,根据一些规则生成相应的文档。默认的模板久很美观,十分适合作为api文档的生成器。目前apidoc支持的注释基本涵盖了大部分语言的风格了,c,java,php,js,python,perl,lua, Erlang…
安装
需要使用npm安装,如果没有安装npm,请先去https://www.npmjs.com/下载npm并且安装。安装之后使用如下命令安装apidoc
npm install apidoc -g
开始API文档
通常我们的api的是通过一个方法的调用,在mvc架构的c层。如果一个api是 /foo/bar ,那么可以在相关的方法调用中这样写注释
/** * @api {GET} /foo/bar 一个测试的接口 * @apiName foobar * @apiVersion 0.1.0 * @apiGroup foo * @apiDescription 这是一个测试的接口,会输出一个hello world */