apidoc 历史版本比较 自定义模板

apidoc对于接口文档的管理还是很不错的，特别是有历史版本比较，下面会详细的说一说。怎么安装apidoc请参考：apidoc 生成api文档

1，配置文件apidoc.json

{
    "name": "btob项目",
    "version": "1.0.0",
    "description": "接口api文档",
    "title": "php接口demo",
    "url" : "http://192.168.5.214",
    "sampleUrl": "http://192.168.5.214",
    "template": {
        "withCompare": true,      //设为true
        "forceLanguage":"zh-cn",
        "withGenerator": false
  }
}

2，自定义模板，apidoc默认模板是支持历史版本比较的

# apidoc -i /home/tank/mytest/ -o /home/tank/doc
# cd /home/tank/doc
# mkdir /home/tank/mytemplate
# cp -r css  img  index.html  locales  main.js  utils  vendor /home/tank/mytemplate
# apidoc -i /home/tank/mytest/ -o /home/tank/doc2 -t /home/tank/mytemplate

这样就定义了一个默认模板一模板了，并重新生成了api文档

3，历史版本比较

怎么创建历史版本呢？

3.1、在项目下建带下划线的文件，不同的语言不同的后缀，例如java就是.java，php就是.php，python就是.py后缀。如下

[root@localhost mytest]# ls
apidoc.json  _sendDetail.php  sendDetail.php  _user.php  user.php

3.2、每次改接口时把注释copy到带下划线的文件中，以后在改版本号

[root@localhost mytest]# cat _user.php
 /**
 * @api {post} /supplier/login.php 用户登录
 * @apiName login
 * @apiGroup Login
 * @apiVersion 1.0.0
 * @apiDescription  用户登录
 * @apiPermission none
 * @apiHeader  Content-Type              application/x-www-form-urlencoded
 * @apiSampleRequest  http://192.168.5.214/supplier/login.php
 * @apiParamExample {json} 请求例子:
 *    body:
 *    {
 *       "mobile": 13712345678,
 *       "operationIp": "192.168.5.200"
 *    }
 * @apiParam {Number} mobile mobile
 * @apiParam {String} operationIp ip
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 200
 * @apiSuccess (200) {String} name 真实姓名
 * @apiSuccess (200) {String} mobile 手机号
 * @apiSuccess (200) {String} birthday 生日
 * @apiSuccess (200) {String} tel 坐机
 * @apiSuccessExample {json} 返回样例:
 * {
 * "code": 200,
 * "msg": "vb",
 * "name": "真实姓名",
 * "mobile": 1234567890aaa1,
 * "birthday": "1980-03-05",
 * "tel": "021-12345678"
 * }
 * @apiErrorExample {json} 错误返回:
 * {
 * "code": -1
 * "message": "操作失败。系统错误"
 * }
 */

 /**
 * @api {post} /supplier/login.php 用户登录
 * @apiName login
 * @apiGroup Login
 * @apiVersion 1.0.1
 * @apiDescription  用户登录
 * @apiPermission none
 * @apiSampleRequest  http://192.168.5.214/supplier/login.php
 * @apiParamExample {json} 请求例子:
 *    body:
 *    {
 *       "mobile": 13712345678,
 *       "operationIp": "192.168.5.200"
 *    }
 * @apiParam {Number} mobile mobile
 * @apiParam {String} operationIp ip
 * @apiSuccess (200) {String} msg 信息
 * @apiSuccess (200) {int} code 200
 * @apiSuccess (200) {String} name 真实姓名
 * @apiSuccess (200) {String} mobile 手机号
 * @apiSuccess (200) {String} birthday 生日
 * @apiSuccess (200) {String} tel 坐机
 * @apiSuccessExample {json} 返回样例:
 * {
 * "code": 200,
 * "msg": "vb",
 * "name": "真实姓名",
 * "mobile": 1234567890aaa1,
 * "birthday": "1980-03-05",
 * "tel": "021-12345678"
 * }
 * @apiErrorExample {json} 错误返回:
 * {
 * "code": -1
 * "message": "操作失败。系统错误"
 * }
 */

3.3、每次发接口时，要用apidoc命令重新生成文档，才会生效

apidoc 历史版本比较