手动搭建koa+ts项目框架（apidoc文档篇）

---

一、安装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文档

---

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