自动生成API文档-apidoc

前言

对于一个后台开发者编写接口文档是必不可少的一件事，但是手动编写又很麻烦，网上出现了很多自动化生成的API文档框架，本篇文章就来介绍一下apidoc的在node开发过程中的基本使用。

用法

• npm安装

对于我们在webstorm或者VScode创建的node后台项目，想要使用一个第三方的库，基本都需要npm安装一下，首先查看一下apidoc的官网（官网地址:http://apidocjs.com/#param-api-private）

全局安装(也可以安装在dev环境)

  npm i apidoc -g   #全局安装

• 环境配置apidoc

两种配置方式:

(1)在根目录中添加apidoc.json文件

{
"name": "example",
"version": "0.1.0", 
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1" 
}

(2)项目package.json配置api-doc

 "apidoc": {
    "title": "叔接口文档",
    "url": "http://localhost:6789"//该代码对应的域名或主机地址
  }

• apidoc文件目录创建

  在根目录的public中创建apidoc文件夹

• 对应路由地址(router)编写接口内容

  node后台项目，在开发过程中都会有一个router路由目录，里面用于存放前端请求的路由地址，每个接口卢有地址上方编写接口文档即可。

  post请求的一个规范：

/**
 * @api {post请求方式} /vip/manager/dropPrivilege 下架删除会员特权
 * @apiName /vip/manager/dropPrivilege
 * @apiGroup vip
 *
 * @apiParam {id} id 会员特权id
 *
 * @apiSuccessExample 请求成功:
 *
 * { code: 0, message: '特权删除成功' }
 *
 * @apiErrorExample 请求失败:
 *
 * { code: -1, message: '无该项特权' }
 */

规范中只是最近本使用，具体的注解参数可以查看这个地址： ApiDoc官网注解说明链接 ：http://apidocjs.com/#param-api
- 项目terminal执行命令行：

apidoc -i routes/ -o public/apidoc/

执行这个命令后出现

info: Done.

表示文档生成成功，这时候会在之前public中创建的apidoc文件中中看到一些代码，其中的index.html文件就是接口文档访问时候展示的内容