Nodejs的apidoc操作

目录

• 前言
• apidoc的安装
• Nodejs文件定义接口信息
• apidoc.json文件
  • • 栗子1
    • 栗子2
• 生成apidoc网页文件

---

前言

• 操作系统win10
• 时间2019年02月
• Nodejs版本：node v8.9.3
• 参考网址1
• 参考网址2

apidoc的安装

npm install apidoc -g

-g参数表示全局安装，这样哪儿都能用了哦

Nodejs文件定义接口信息

/** 
 * @api {POST} http://127.0.0.1:8000/login/ 登录操作
 * @apiVersion 0.0.1
 * @apiName login
 * @apiGroup User
 * @apiDescription 这里可以描述一下这个函数的具体操作
 * 这一行也是可以描述的
 * 
 * @apiParam {String} name 姓名
 * @apiParam {String} password 密码
 * 
 * @apiSuccess {Object} status 状态码
 * @apiSuccess {Object} msg 简略描述
 * 
 * @apiSuccessExample Response-Success:
 *     HTTP 1.1/ 200K
 *     {
 *         'status': 0,
 *         'msg': 'success'
 *     }
 * @apiErrorExample Response-Fail:
 *     HTTP 1.1/ 404K
 *     {
 *         'status': 0,
 *         'msg': 'Fail'
 *     }
*/
function login(name, password) {
    console.log(name, password);
    return {
        'status': 0,
        'msg': 'success'
    };
};

apidoc.json文件

栗子1

{
  "name": "我的apidoc示例",
  "version": "0.0.1",
  "description": "这是一句描述，描述了api文档",
  "title": "API DOC EXAMPLE"
}

栗子2

这种栗子中需要在apidoc.json文件的当前路径下分别新建header.md和footer.md文件
apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apidoc test1",
  
  "header": {
    "title": "这不是头",
    "filename": "header.md"
  },
  "footer": {
    "title": "这不是尾",
    "filename": "footer.md"
  }
}

header.md

# Example text from header.md

This text is from file "header.md".

## <span id="api-example-for-a-submenu-entry">HowTo include</span>

In your projects "package.json" you can set "apidoc.header" with a title and a filename to include this file into your documentation.

This example attempts to integrate "header.md" and "footer.md".

    {
      "name": "example",
      "version": "0.3.0",
      "description": "apidoc example project.",
      "apidoc": {
        "header": {
          "title": "My own header title",
          "filename": "header.md"
        },
        "footer": {
          "title": "My own footer title",
          "filename": "footer.md"
        }
      }
    }

footer.md

# Example text from footer.md

This text is from file "footer.md".

## HowTo include

Watch header.md for further information.

生成apidoc网页文件

apidoc -i 代码所在路径 -o 生成文件的路径

此时会在指定的生成文件路径中生成一个apidoc的文件夹，里面的index.html文件就是啦啦啦啦~~~