代码生成 API文档 神器：apidoc

apidoc 是一款非常好用的代码生成文档的 工具，页面绚丽多彩(花里胡哨)，对于前端对接API来说是非常的友好。 话不多说，先看一下 demo

下面讲解使用组合套件：JS/TS + apidoc + VSCode

步骤一：全局安装 apidoc

npm install -g apidoc

步骤二：创建 apidoc.json

创建项目->在根目录下 创建 apidoc.json。

{
    "name": "demo",
    "version": "0.1.0",
    "description": "demo api documents",
    "url": "http://localhost:3000"
}

示例是基本配置，更多配置点这里

步骤三：VSCode 插件 ApiDoc Snippets

在 vscode 扩展商店 搜索 ApiDoc Snippets，安装。

步骤四：在函数名 输入 apiDocument

小技巧：输入API就会提示一些列表

找到适合的补全。每个字段的解释 看这里

下面给出一个示例：

	/**
     * @api {GET} /api/users/:id getUserById
     * @apiName getUserById
     * @apiGroup User
     * 
     * @apiParam  {String} id 用户ID
     * 
     * @apiSuccess  {Number} code 成功时返回 200
     * 
     * @apiParamExample  {Object} Request-Example:
     * {
     *      id: 1
     * }
     * 
     * @apiSuccessExample {type} Success-Response:
     * {
     *      id: 1,
     *      name: "章三",
     *      age: 25,
     *      hobbies: [
     *          {name: "象棋", en_name: "chinese_chess", key: "chess"},
     *          {name: "篮球", en_name: "basketball", key: "basketball"}
     *      ]
     * }
     * 
     */

步骤五：生成接口文档

终端输入 apidoc -i sourceDir/ -o targetDir

sourceDir 是选择 要生成哪些目录下的API，target 是要生成到哪个目录。

比如 apidoc -i controller/ -o public/apidoc/

这时候就可以看到 public/apidoc 下有生成后的静态文件，打开 index.html 就是 最终的效果，一般 生成后的文档 放在 服务端的静态服务器 这样前端开发人员 可以直接访问这份文档。

效果图：

ok，齐活！更多使用，参数详解 移步 官网