手动搭建koa+ts项目框架(apidoc文档篇)

文章目录

  • 一、安装`apidoc`工具
  • 二、使用
    • 1、项目根目录新建`apidoc.json`
    • 2、定义接口路由上方注解对应信息
    • 3、配置静态文件访问目录
    • 4、生成api文档
    • `如有启发,可点赞收藏哟~`


一、安装apidoc工具

全局安装

npm i apidoc -g

查看是否安装成功

apidoc -v

手动搭建koa+ts项目框架(apidoc文档篇)_第1张图片

二、使用

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文档


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

你可能感兴趣的:(node.js,前端)