---

一、安装apidoc工具

全局安装

npm i apidoc -g

查看是否安装成功

apidoc -v

二、使用

1、项目根目录新建apidoc.json

{"name": "Admin-Api","version": "1.0.0","description": "权限管理系统API文档","title": "权限管理系统API文档","url": "http://localhost:3000","sampleUrl": "http://localhost:3000","forceLanguage": "zh-cn","template": {"withCompare": true,"withGenerator": true}
}

• name: 项目名称
• version: 项目的版本
• description: 项目简介
• title: 浏览器的标题文字
• url: 在线文档地址
• sampleUrl: 窗体来测试API方法（发送请求）
• forceLanguage: 浏览器语言
• template: 设置特定于apiDoc的默认模板
• withCompare 布尔 启用与旧的API版本比较。默认：true
• withGenerator 布尔 在输出页脚中产生的信息。默认：true
• …
• 更多

2、定义接口路由上方注解对应信息

详细可

/*** @api {method} path [title]* @apiDefine name [title] [description]* @apiDescription text* @apiError [(group)] [{type}] field [description]* @apiErrorExample [{type}] [title]* example* @apiExample [{type}] title* example* @apiGroup name* @apiHeader [(group)] [{type}] [field=defaultValue] [description]* @apiHeaderExample [{type}] [title]* example* @apiIgnore [hint]* @apiName name* @apiParam [(group)] [{type}] [field=defaultValue] [description]* @apiParamExample [{type}] [title]* example* @apiPermission name* @apiSampleRequest url* @apiSuccess [(group)] [{type}] field [description]* @apiSuccessExample [{type}] [title]* example* @apiUse name* @apiVersion version*/
export const userInfo = () => {}

3、配置静态文件访问目录

需安装koa-static
项目入口文件新增

// 配置在线接口文档，放在 public 中，访问 localhost:端口
app.use(require('koa-static')(__dirname + '/api-doc'))

4、生成api文档

在项目更目录执行，或者在package.json配置对应生成脚本

{"scripts": {..."api-doc": "apidoc -i ./src/routes -o ./api-doc",}
}

• -i 对应需要解析的目录
• -o 输出目录

执行npm run api-doc生成目录
访问http://localhost:3000/查看生成的api文档

---

如有启发，可点赞收藏哟~