JS/TS + apidoc + VSCode 自动生成 接口文档

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

步骤一：全局安装 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，齐活！更多使用，参数详解 移步 官网