一、前言

前后端分离的开发模式下，前后端沟通的成本增加，如何减少口头的交流成了关键。

这时有一份高端大气的接口文档就非常开心了。

二、接口文档 （API 接口文档）

1. 是什么

一份描述了后端每个API接口的详细文档。主要需要如下几点信息：

  1. 请求方式
  2. 请求地址
  3. 请求参数
  4. 后端响应

2. 有什么用

减少与前端的口头沟通的成本。方便前端同学快速开发与联调。书面凭证

3. 如何用

  1. 手写 word 、markdown、记事本都是可以的。
  2. 通过一些工具来生成，省时省力。

三、ApiDoc 的使用

官网链接

1. 全局安装

  1. $ npm install apidoc -g

2. 项目根目录下配置 apidoc.json

  1. {
  2.   "name": "example",
  3.   "version": "0.1.0",
  4.   "description": "apiDoc basic example",
  5.   "title": "Custom apiDoc browser title",
  6.   "url" : "https://api.github.com/v1"
  7. }
  • name API接口文档名称
  • version API接口文档版本号
  • description API接口文档简要描述
  • title API接口文档生成的网页标题
  • url API接口文档中请求的基本路径

3. 按照 ApiDoc 的规范给每个路由代码编写注释

4. 在项目根目录下运行命令，生成API接口文档

  1. $ apidoc -i ./ -o ./public/apidoc
  • -i 输入源目录名。项目文件的位置。
  • -o 输出目录名。放置生成的文档的位置。

四、关于是否应该全局安装还是项目本地安装 ApiDoc 工具

基于 Node 的一些工具模块，一般来说我们全局安装即可。比如 nodemon、gulp、live-server、apidoc …

安装完成在系统的任何目录中都可以直接使用他们提供的命令，简单又方便。

但是思考如下的这种情况（假设）：

项目A在早期全局使用的 ApiDoc 是 1.x 版本的。
过了一段时间之后，ApiDoc 升级换代到 2.x 版本，并且这个版本不向下兼容。
新加入到项目A的开发人员在不知道需要安装那个版本的情况下，默认全局安装的 2.x 版本，运行起来就会出现一些意外的问题。

这时如果早期就是在项目本地安装的话，就不会产生这个问题了，因为在 package.json 中有版本号限制。

那么，项目本地安装的工具包，该如何运行呢：

  1. 直接进入到项目本地的 node_modules/.bin 目录中运行
  2. 使用 npx 运行。（npm 在 5.x 版开始，增加了 npx 命令）
  3. 写 npm script 。