apidoc 后端接口注释文档简单使用

apidoc使用指南

一、安装

# 全局安装
npm install apidoc -g   
# 查看是否安装成功,显示命令行参数
apidoc -h 

二、具体使用

    # 1.在项目文件夹新建apidoc.json;
    # 2.在项目根目录运行
    # apidoc -i 源目录 -o  目标目录
    apidoc -i ./router -o ./publish
    # 简写指令
    apidoc

说明：上面的指令可以直接简写为 apidoc，没有任何参数时，默认从当前目录(包括子目录)下格式为(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文档并将输出写入 ./doc/。

三、基本配置

项目根目录下的 apidoc.json 可配置项包含有关项目的常用信息，如 标题，简短描述、版本和配置选项，如页眉/页脚设置或模板特定选项。

1.基本配置方式（apidoc.json）

{
    "name": "user",
    "version": "1.0.0",
    "description": "用户操作接口文档",
    "title": "user",
    "url": "http://127.0.0.1:3000"
}

2.在含有package.json文件的项目中配置(添加"apidoc":{}参数)

 {
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

四、使用

在相关接口上插入注释，例：

/**
 * @api {get} /getuser 用户需求
 * @apiVersion 1.0.0
 * @apiGroup getUser
 *
 * @apiParam {String} id 用户id
 * @apiParam {String} uname 用户名-非空
 * @apiParam  {String} uage 年龄

 * @apiSuccess {Object} status 状态
 * @apiSuccess {Object} msg  提示信息
 * @apiSuccess {String[]} data  返回数据
 *
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *          "status":0,
 *          "reason":"查询成功",
 *          "data":[]
 *      }
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */
router.get('/getuser', (req, res, next) => {
    var sql = 'update user set ? where id=?';
    var body = {
        id: req.query.id,
        uname: req.query.uname,
        uage: req.query.uage
    }
    conn.query(sql, [body, body.id], (err, result) => {
        if (err) console.log(result);
        console.log(result);
    })
})

再使用命令

    apidoc -i ./router -o ./publish

即可生成接口文档，打开./publish/apidoc/index.html即可查看接口文档

效果如下：

参考：
https://www.jianshu.com/p/0a3...
http://apidocjs.com/