apidoc 自动化生成 api接口文档

手写api接口太麻烦. 学习了apidoc自动生成接口文档,这边做一下整理

要用组件那就必须先安装 apidoc,做一下全局安装

npm install apidoc -g

新建配置文件apidoc.json

{
  "name": "test-server",
  "version": "1.0.0",
  "description": "测试API文档",
  "title": "test-server API",
  "url": "http://127.0.0.1:3000",
  "forceLanguage": "zh-cn"
}

在要存放接口文档的目录下创建一个 apidoc 空目录,用来存放生成的接口文件,我是放在public目录下

写api的接口注释 ,如上图右侧注释部分,相关解释可去官网 https://apidocjs.com 查看或者自己摸索一下

/**
 * @api {post} /postUser 测试api
 * @apiDescription 测试api
 * @apiName text
 * @apiGroup User
 * @apiParam {string} account 用户账号
 * @apiParam {string} password 用户密码
 * @apiHeader {String} Authorization  用户授权token
 * @apiSuccess  msg 返回消息
 * @apiSuccessExample {json} Success-Response:
 *  {
      code : 200,
      msg: '认证token成功',
    }
 * @apiSampleRequest http://127.0.0.1:3000/postUser
 * @apiVersion 1.0.0
*/

最后一步就是生成api接口文档 ,在项目下执行命令:-i 指输入 对 routes目录下文件进行编译 -o指输出 输出到public/apidoc目录下

apidoc -i routes/ -o public/apidoc/

项目运行起来,在浏览器输入api接口文档的浏览地址,就能看到自动生成的接口文档了