apidoc文档

1、需求：需要根据api生成文档

2、思路：目前看到node的两种解决方案apidoc和swagger，apidoc的原理是根据文件中的注释来生成文档，swagger是根据一个集合的json文件来生成文档，个人觉得apidoc比较符合个人口味，因为它是根据注释来生成文档，当修改api的时候也可以顺手修改注释，不像swagger还要专门去json文件处修改

3、使用

先全局下载

npm install -g apidoc

在项目中的根目录新建一个apidoc.json文件

{
    "name":"app",
    "title":"app api",
    "description": "这是一个简单的api文档",
    "url":"http://localhost:3000/",
    "sampleUrl": "http://localhost:3000/",//生成body测试的url
    "template": {
        "showRequiredLabels": true,//显示非可选参数的“必需”标签
        "withCompare": true,
        "withGenerator": true,
        "aloneDisplay": true //单击菜单标题时，仅在页面上显示该内容
    }
}

在接口处写上注释，比如在router中写，具体的规则可以查看官网：https://apidocjs.com/，注意不同的参数规则不同如：post用@apiBody，get用@apiParam（具体可以查看官方demo：https://github.com/apidoc/apidoc/tree/master/example，demo展示：https://apidocjs.com/example/），VSCode里面也有个apidoc的插件ApiDoc Snippets，可以更方便的生成注释

/**
 * @apiDefine users 用户管理
*/

/**
    * @api {post} users/register 用户注册
    * @apiName 用户注册
    * @apiGroup users
    * @apiBody {String} nickname 昵称
    * @apiBody {String} email 邮箱
    */
/**
 * @api {post} users/login 用户登录
 * @apiName 用户登录
 * @apiGroup users
 * @apiBody {String} email 邮箱
 */

然后输入指令生成文档（-i：输入路径，-o：输出路径），比如我的注释是在router文档里面的，现在要生成文档在public/apidoc/这个路径

apidoc -i router/ -o public/apidoc/

生成完的文档，配置静态服务，就可以打开了

 在浏览器输入http://localhost:3000/apidoc/index.html，就可以查看了