使用apidoc工具编写自动化API文档

API文档可以帮助我们快速理解接口的调用方法，因此一份好的API文档其实是非常重要的。但是对于开发者来说编写API文档又是比较耗时，这个时候我们希望有一些工具可以帮助我们节省时间，提升效率，apidoc工具就是其中之一。很多语言都会提供自动化文档的工具，方法也大同小异，我选择的是apidoc，官网是：http://apidocjs.com/

apidoc主要是通过支持不同语言的注释方法来识别，目前已经支持了以下语言，如图所示，而且新的版本也支持了lua，不过官网的文档还没及时更新。

a1.png

我个人认为apidoc最好的使用场景是程序员在完成一个API时按照apidoc的语法在接口文件上面编写接口的调用方法，然后再使用apidoc识别直接生成文档，因为接口的开发者对接口的调用是最为熟悉的，这样可以最小程度的减少后续编写文档的时间。

下面介绍apidoc的使用方法：
1、安装工具

---

(1)安装npm包管理工具

    sudo apt-get install npm

(2)安装nodejs

    sudo apt-get install nodejs

如果终端输入:node -v会输出版本号则说明安装成功。

(3)安装apidoc工具
官网：http://apidocjs.com

    npm install apidoc -g

一般默认会安装在：/usr/local/lib/node_modules/apidoc 目录下。

(4)测试apidoc

    cd /usr/local/lib/node_modules/apidoc
    apidoc -i explame -o doc

查看doc目录，里面会生成静态的html文件，直接浏览器打开即可。

2、按照apidoc语法编写接口注释

(1)准备好lua文件和json配置文件，这里以我的工程为例：

    mkdir orskycloud-apidoc
    cd orskycloud-apidoc
    mkdir apidoc
    touch apidoc.json

apidoc.json:

     {                                                                                                                                          
    "name":"orskycloud API",                                                                                                               
    "version":"1.0.0",                                                                                                 
    "title":"ORSkyCloud API Document",
    "description":"ORSkyCloud开发者指南"
    }                                                                                                                                          

api/test.lua

--[[
@apiDefine Response
@apiParam(response){string} Message 响应信息，接口请求success或failed返回相关信息
@apiParam(response){bool} Successful 是否成功。通过该字段可以判断请求是否到达.
--]]
--[[
@api {POST} http://hcwzq.cn/api/getalldevicesensor.json?uid=* getalldevicesensor
@apiName getalldevicesensor
@apiGroup All
@apiVersion 1.0.1
@apiDescription 获取用户所有设备和传感器信息

@apiParam {string} uid 唯一ID，32位md5值
@apiParam {json} response 响应数据
@apiUse Response


@apiParamExample Example:
POST http://hcwzq.cn/api/getalldevicesensor.json?uid=c81e728d9d4c2f636f067f89cc14862c

@apiSuccessExample {json} Success-Response:
HTTP/1.1 200 OK
{"1":[{
    "createTime":"2016-12-19 23:07:12",
    "deviceName":"Test1",
    "description":"description1",
    "Sensor":[{
        "createTime":"2016-9-12 00:00:00",
        "unit":"kg",
        "name":"weight",
        "designation":"体重"}]
}],
"Message":"success",
"Successful":true
}

@apiErrorExample {json} Error-Response:
HTTP/1.1 200 OK  
{
        "Successful":false,
        "Message": "Device not create yet"
}

--]]

这里我省略了我的接口的内容，注意：lua的注释要用--[[ --]]，其它注释方法是无效的，官网我也没看到有介绍，但是用这个亲测可用，哈。文件的注释编写好之后按照第一步的方法使用apidoc生成就可以了。

下面是一些apidoc语法的简单介绍，更加详细的大家去查阅官网的文档(参考博文：http://www.jianshu.com/p/bb5a4f5e588a)：

@api {method} path [title]
  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单(@apiGroup)下的小菜单
  method可以有空格，如{POST GET}
@apiGroup name
  分组名称，被解析为导航栏菜单
@apiName name
  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面@api会覆盖前面定义的@api
@apiDescription text
  接口描述，支持html语法
@apiVersion verison
  接口版本，major.minor.patch的形式

@apiIgnore [hint]
  apidoc会忽略使用@apiIgnore标注的接口，hint为描述
@apiSampleRequest url
  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种

@apiDefine name [title] [description]
  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块
  在@apiDefine内部不可以使用@apiUse
@apiUse name
  引入一个@apiDefine的注释块

@apiParam [(group)] [{type}] [field=defaultValue] [description]
@apiHeader [(group)] [{type}] [field=defaultValue] [description]
@apiError [(group)] [{type}] field [description]
@apiSuccess [(group)] [{type}] field [description]
  用法基本类似，分别描述请求参数、头部，响应错误和成功
  group表示参数的分组，type表示类型(不能有空格)，入参可以定义默认值(不能有空格)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  用法完全一致，但是type表示的是example的语言类型
  example书写成什么样就会解析成什么样，所以最好是书写的时候注意格式化，(许多编辑器都有列模式，可以使用列模式快速对代码添加*号)

@apiPermission name
  name必须独一无二，描述@api的访问权限，如admin/anyone

最后的效果图：

a2.png

a3.png

这里只是提供一种方法，有更加省事的途径欢迎大家评论交流，内容错漏之处敬请见谅，谢谢啦。