在使用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 */
这样一个最简单的apidoc支持的注释就出现了,接着要做的就是将这些注释生成一袭html文档。在项目的根目录需要建立一个名字为apidoc的json文档
{ "name": "test", "version": "0.1.0", "title": "测试项目", "description": "这是一个测试的项目", "url": "http://www.imhuchao.com" }
这些意思都很好了解,name的意思为项目名称,version为版本号,title为项目标题,description为项目的描述,url为接口的地址。比如这里的url是http://www.imhuchao.com,上面写了一个测试接口为/foo/bar,那么生成的文档中的接口地址就会是 http://www.imhuchao.com/foo/bar。
有了apidoc.json,接下来就可以进行文档的生成了,命令为
apidoc -i [input dir] -o [output dir]
需要指定输入和输出的地址,用手敲命令执行比较麻烦,因此我一般是在项目中新建一个脚本,执行脚本就可以自动生成。比如php的可以是
$input = __DIR__; $output = __DIR__ . '/apidoc'; $shellout = ''; exec("apidoc -f \".*\\.php$\" -i {$input} -o {$output}", $shellout); //这里只需要扫描php文件,其他的文件不生成注释 print_r($shellout);
其他的语言也类似了,或者在linux或者mac上直接使用shell脚本就可以。
关于apidoc命令的使用,可以使用apidoc -h来查看其他的参数,比如自定义模板之类的。
apidoc注释支持的标签
- @api
- @apiDefine
- @apiDeprecated
- @apiDescription
- @apiError
- @apiErrorExample
- @apiExample
- @apiGroup
- @apiHeader
- @apiHeaderExample
- @apiIgnore
- @apiName
- @apiParam
- @apiParamExample
- @apiPermission
- @apiPrivate
- @apiSampleRequest
- @apiSuccess
- @apiSuccessExample
- @apiUse
- @apiVersion
更详细的可以去 http://apidocjs.com/ 查看apidoc的使用。
赞赏微信赞赏
支付宝赞赏