是时候解放常年写接口文档的程序猿们啦

工作中我们经常会写接口文档，今天我们就来说说使用apidoc自动生成接口文档.
首先我们电脑要安装了nodejs和npm环境，可以检查下是否安装了如下：

liuxiaomodeMacBook-Pro:~ momo$ node -v
v10.15.2
liuxiaomodeMacBook-Pro:~ momo$ npm -v
6.4.1
liuxiaomodeMacBook-Pro:~ momo$ 

如果没有安装到官网进行下载安装 nodejs官网一般直接下载首页推荐的版本就行，安装之后也会一并帮我们把npm安装好，就可以使用上面的命令查看是否安装完成
接下来我们就使用npm安装apidoc,命令如下

 npm install apidoc -g

接下来我们就可以使用嘞apidoc -h能使用此命令可以查看帮助，也就说明安装成功了
这里我就以PHP项目为例介绍下具体操作方法
1、在项目根目录创建一个文件apidoc.json 内容如下

{
  "name": "ShopsAPIs", //文档项目名
  "version": "1.0.0", //文档版本号
  "description": "商城接口文档", //文档描述
  "title": "商城接口文档", //网页的title名称
  "url" : "https://shop.mayspie.com" //接口域名地址
}

2、我们在需要生成文档的方法里面添加注释如下：

class TestClass
{
       /**
         * 定义一个变量 用于apiGroup 因为不支持直接输入中文
         * @apiDefine test 测试
         */
     /**
     * @api {put} /api/address/setdefault/:addrid 设置默认地址
     * @apiName setDefault
     * @apiGroup test
     * @apiDescription 用户设置某个地址为默认地址
     * @apiVersion 1.0.0
     *
     * @apiParam {string} token 用户签名token
     * @apiParam {int} addrid 地址id
     * @apiParam {int} datatype 0取消默认;1设置默认
     *
     * @apiSuccess {int} status 状态值
     * @apiSuccess {string} msg 状态描述
     * @apiSuccessExample Success-Response:
     * {
        "status": 0,
        "msg": "操作成功"
        }
     * @apiErrorExample {json} Error-Response:
     * {
        "status": -1,
        "msg": "操作失败"
        }
     * @apiError 0 请求成功
     * @apiError -1 请求失败
     * @apiError -3 未登录
     */
    function test()
    {
    }
}

生成文档命令（application/api/ 这个为我需要生成文档的方法文件目录，public/apidoc/为我希望生成之后文档的存放目录,大家可以根据实际需求改目录）

apidoc -i application/api/ -o public/apidoc/

效果如下图：

我们来解释下apidoc的相关注释

@api {put} /api/address/setdefault/:addrid 设置默认地址
这句话是设定接口请求类型put  后面是接口地址  最后文字是接口名称

@apiName 这个设定接口名称  不会影响文档展示内容

@apiGroup  这个是给接口定义一个组名

@apiDescription  接口的描述信息

@apiVersion  设定接口版本号

@apiParam  设定请求参数

@apiSuccess 设定请求成功响应参数

@apiSuccessExample  成功响应示例

@apiErrorExample   失败响应示例

@apiError  失败响应状态码

@apiExample Example usage:

API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:”。

 

你学会嘞么