Ubuntu安装apiDoc以及入门教程

一.apiDoc简介

apiDoc是用来生成RESTful风格Web API文档的工具，支持现在流行的大部分编程语言，如Python,Java,C#, Go, Dart, Java, 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 id 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文档？
答案当然是肯定有的了，有兴趣的可以自己找找看或自己写写看，如果写好了可以告诉我哦。

参考链接：http://www.jianshu.com/p/2b24cd430a7d