ApiDoc + github page 使用

你的项目在用什么工具书写api文档？今天就来给大家推荐下ApiDoc

1. ApiDoc是什么？

ApiDoc可以根据你再代码里的注释，来生成api描述文档，这样就不用你自己去告诉端的小伙伴该怎么调用你的api了。目前支持的变成语言有：Java，Javascript，Php，Python,C#,Ruby,Lua等，主流的编成语言都支持。

2. 怎么用？

很简单，只要在你的代码里用这样的注解申明你的接口信息就好

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *  * @apiParam {Number} id Users unique ID.
 *  * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

这里面的这些注解都是ApiDoc定义好的，你只要按照官方文档使用就好了。ApiDoc 官网

3. 开始搞起来

• 安装

npm install apidoc -g

• 运行

apidoc -i api/ -o docs/

api是你的代码目录也就是你使用注释的文件目录，它会自动扫描使用注解的文件。docs文件时你要生成api文档的目录，也是github page最后要使用的目录。

• 检查api文档

在docs目录下直接打开index.html就可以查看最终结果了。

4. github page

github page 是一项免费的web服务，它允许你把你的静态页面发布出去共其他用户通过浏览器查看。刚才我们生成的文档内容都在我们本地，现在我们需要把它发布到github上

• 创建github仓库
• 将自己的生成后的戴阿曼上船，就是docs整个目录
• 在仓库的 setting中开启page服务
• 用page提供的url去访问

总结

ApiDoc提供了更好的api文档阅读体验，对于开发者来说免去了写文档的麻烦。不过不足就是不能像swagger那样提供在线调试，而且要想描述一个api需要些很多的注释。