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

张映 发表于 2017-11-10

分类目录: 服务器相关

标签:, ,

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 历史版本比较

apidoc 历史版本比较



转载请注明
作者:海底苍鹰
地址:http://blog.51yip.com/server/1880.html