apidoc 配置

APIDOC

1. npm install apidoc --save-dev

2. 在 package.json 添加文档生成脚本

   "scripts": {
     "docs": "apidoc -i routes/ -o docs/"
   }
   

3. 生成文档

   npm run docs
   

在 VSCode 中快速生成 apidoc 注释

1. 安装插件: JavaScript (ES6) code snippets

2. 点击顶部菜单 → 代码 (Code) → 首选项 (Preferences) → 用户代码片段 (Configure Snippets), 选择js/ts

   {
     "API Doc Comment": {
       "prefix": "apidoc",
       "body": [
         "/**",
         " * @api {${1|GET,POST,PUT,DELETE|}} ${2:/path} ${3:描述接口功能}",
         " * @apiName ${4:接口名称}",
         " * @apiGroup ${5:分组名称}",
         " * @apiPermission ${6:权限要求}",
         " * @apiVersion ${7:1.0.0}",
         " * @apiHeader {String} Authorization Bearer Token",
         " * @apiQuery {Number} [page=1] 当前页码",
         " * @apiQuery {Number} [pageSize=20] 每页条目数",
         " * @apiSuccess {Boolean} success 请求成功标志",
         " * @apiSuccess {Object[]} data 数据",
         " * @apiSuccess {Number} data.id 日志ID",
         " * @apiSuccess {String} data.action 执行的操作",
         " * @apiSuccess {String} data.timestamp 操作时间",
         " * @apiError (401) Unauthorized 未登录或无权限",
         " * @apiSampleRequest /user/register",
         " * @apiExample {json} 成功示例:",
         " * {",
         " *   \"success\": true,",
         " *   \"data\": {",
         " *     \"id\": 1,",
         " *     \"username\": \"john_doe\"",
         " *   }",
         " * }",
         " */",
       ],
       "description": "快速生成 apidoc 注释"
     }
   }