通过apidoc 自动化生成 api接口文档

学习node的过程中,会涉及到api接口的编写.后端的api接口是用来给前端调用的,这时候就需要api接口文档来做前后端的沟通桥梁.  手写api接口太麻烦.  学习了apidoc自动生成接口文档,这边做一下整理:

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

    npm install apidoc -g

2. 配置文件,我是直接配置在项目的package.json文件里

 "apidoc": {  

    "title": "接口文档",

    "url": "http://localhost:3000"

  }

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

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

/**

 * @api {post} /api/v0/user/doLogin 用户登录

 * @apiDescription 用户登录

 * @apiName doLogin

 * @apiGroup User

 * @apiParam {string} phoneNum 手机号（eq:15220064294）

 * @apiParam {string} countryCode 国家代码（eq: 86）

 * @apiParam {string} email 用户邮箱([email protected])

 * @apiParam {string} loginType 登录类型 (1:手机验证码登录 2:手机号密码登录 3:邮箱密码登录,4:邮箱验证码登录)

 * @apiParam {string} messageCode 手机验证码(eq: 123456)

 * @apiParam {string} password 密码 // 非必填，与短信验证码选其一

 * @apiSuccess {json} result

 * @apiSuccessExample {json} Success-Response:

 *  {

 *    data: {

 *      comments: ""

 *      date: "2018-11-13 12:09:29"

 *      email: "[email protected]"

 *      enable: true

 *      group: "0"

 *      id: "zwwdJvLmP"

 *      logo: "/upload/images/defaultlogo.png"

 *      userName: "doramart"

 *      token: "eyJkYXRhIjp7InVzZXJJZCI6Inp3d2RKdkxtUCIsInBob25lTnVtIjoxNTIyMDA2NDI5NH0sImNyZWF0ZWQiOjE1NDI2NDMyNTAsImV4cCI6MzYwMH0=.SW3JVAjkQUX0mgrSBuOirB3kQV6NNatlc4j/qW7SxTM="

 *    } 

 *    message: "登录成功"

 *    server_time: 1542089573405

 *    status: 200

 *  }  

 * @apiError {json} result

 * @apiErrorExample {json} Error-Response:

 *  {

 *    data: {}

 *    message: "验证码错误"

 *    server_time: 1542082677922

 *    status: 500

 *  }

 * @apiSampleRequest http://localhost:8080/api/v0/user/doLogin

 * @apiVersion 1.0.0

 */

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

apidoc -i routes/ -o public/apidoc/

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

http://localhost:3000/apidoc/index.html