一.apiDoc简介
apiDoc是用来生成RESTful风格Web API文档的工具，支持现在流行的大部分编程语言，如Python,Java,C#,Go,Dart,JavaScript,PHP,Scala 等。在源代码的注释中使用apiDoc提供的注解信息来生成文档信息。
在我们日常开发中一定会写开发文档，以前常见的做法是维护一个或多个markdown文件，每次api改动时都要去对应文件位置进行修改。这种方式维护起来相当麻烦，而且相对于网页来说markdown只能提供简单的阅览功能不能实时查看接口调用结果，对开发者来说api也不友好。所以找一个更好的文档处理方式已经是迫在眉睫，现在apiDoc可以让你可以解脱了。
apiDoc的gitHub地址：https://github.com/apidoc/apidoc。
apiDoc的文档地址：http://apidocjs.com/
二.Ubuntu安装apiDoc
按照官方文档安装apiDoc会出现一些问题。主要原因是因为apiDoc需要依赖nodejs，所以需要先安装nodejs然后安装apiDoc就可以了。
2.1 安装nodejs
更新ubuntu软件源
sudo apt-get update
sudo apt-get install -y python-software-properties software-properties-common
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
安装nodejs
sudo apt-get install nodejs
sudo apt install nodejs-legacy
sudo apt install npm
更新npm的包镜像源
sudo npm config set registry https://registry.npm.taobao.org
sudo npm config list
全局安装n管理器(用于管理nodejs版本)
sudo npm install n -g
安装最新的nodejs（stable版本）
sudo n stable
sudo node -v
2.2安装apiDoc
上面的操作顺利完成后再执行下面命令就OK了。
sudo npm install apidoc -g
三.apiDoc入门
3.1 运行官方Demo
首先下载官方github上的源代码。
然后进入
apidoc/example/
最后执行
apidoc -i example/ -o doc/
这个命令就能满足基本需求了，详细的命令参数查看官方文档。生成的文档在指定的文件doc中，打开index.html。官方在线例子
3.2 配置文件介绍
如Demo中的文件结构
.
├── _apidoc.js 需要生成api文档的源代码文件
├── apidoc.json 配置文件
├── example.js 需要生成api文档的源代码文件
├── footer.md 生成api文档的自定义头部信息，支持markdown标签。
└── header.md 生成api文档的自定义底部信息，支持markdown标签。
apidoc.json文件相当简单对比Demo生成的文档可以轻松理解。
{
"name": "apidoc-example-test","version": "0.3.0","description": "apidoc example project","title": "Custom apiDoc browser title","url" : "https://api.github.com/v1","sampleUrl": "https://api.github.com/v1","header": { "title": "My own header title","filename": "header.md" },"footer": { "title": "My own footer title","filename": "footer.md" },"template": { "withCompare": true,"withGenerator": true } }
3.3 常用注解介绍
具体文档可参考：http://apidocjs.com/
/**
* @api {get} /user/:id Read data of a User
* @apiVersion 0.3.0
* @apiName GetUser
* @apiGroup User
* @apiPermission admin
*
* @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
*
* @apiParam {Number} id The Users-ID.
*
* @apiExample Example usage:
* curl -i http://localhost/user/4711
*
* @apiSuccess {Number} id The Users-ID.
* @apiSuccess {Date} registered Registration Date.
* @apiSuccess {Date} name Fullname of the User.
* @apiSuccess {String[]} nicknames List of Users nicknames (Array of Strings).
* @apiSuccess {Object} profile Profile data (example for an Object)
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
* @apiSuccess {Object[]} options List of Users options (Array of Objects).
* @apiSuccess {String} options.name Option Name.
* @apiSuccess {String} options.value Option Value.
*
* @apiError NoAccessRight Only authenticated Admins can access the data.
* @apiError UserNotFound The <code>id</code> of the User was not found.
*
* @apiErrorExample Response (example):
* HTTP/1.1 401 Not Authenticated
* {
* "error": "NoAccessRight"
* }
*/
function getUser() { return; }
重点介绍下@apiParam：
语法：
@apiParam [(group)] [{type}] [field=defaultValue] [description]
描述如何将参数传递给你的api方法。文档描述
例如: @apiParam (MyGroup) {Number} id Users unique ID.
注意：该标签适用于三种参数形式
a.动态路由：http://localhost/sutdent/:id
b.请求参数：http://localhost/sutdent?id=:id
c.表单参数：http://localhost/sutdent
在生成文档中id参数可以在“Send a Sample Request”发送时被替换成具体的值方便查看api的返回结果。
一个问题
这里抛出一个问题：apidoc是比较“底层”的文档生成方式，能否不手动写apiDoc的标签而是直接根据后端代码基于apiDoc来直接生成api文档？
答案当然是肯定有的了，有兴趣的可以自己找找看或自己写写看，如果写好了可以告诉我哦。
