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

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

步骤一:全局安装 apidoc

1
npm install -g apidoc

步骤二:创建 apidoc.json

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

1
2
3
4
5
6
{
"name": "demo",
"version": "0.1.0",
"description": "demo api documents",
"url": "http://localhost:3000"
}

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

步骤三:VSCode 插件 ApiDoc Snippets

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

步骤四:在函数名 输入 apiDocument

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

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

下面给出一个示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
/**
* @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,齐活!更多使用,参数详解 移步 官网

原创技术分享,您的支持将鼓励我继续创作