在开发API接口的过程中，为了让前端人员能快速的理解和调用我们写的API，接口文档是必不可少的。虽然现在已经有很多文档管理工具，但是有时候需要手动去添加显得非常麻烦。这里我们就使用apiDoc来搭建我们的接口文档管理工具，只要你在接口中安装规定的格式去注释好，那么就可以自动进行生成。本文我们将介绍apiDoc的安装和使用。

一、首先安装Node

1、下载node

[root@localhost ~]# wget https://npm.taobao.org/mirrors/node/v10.11.0/node-v10.11.0-linux-x64.tar.xz

2、解压到指定的目录并进入到解压后的目录

[root@localhost ~]# tar -xf node-v10.11.0-linux-x64.tar.xz -C /apps
[root@localhost ~]# cd /apps/
[root@localhost apps]# ln -s node-v10.11.0-linux-x64/ node #为目录创建软链接

3、创建软链接

[root@localhost apps]# ln -s /apps/node/bin/node /usr/local/bin
[root@localhost apps]# ln -s /apps/node/bin/npm /usr/local/bin

4、查看版本

[root@localhost apps]# node -v
v10.11.0

二、安装apiDoc

1、按照apiDoc

[root@localhost apps]# npm install apidoc -g
npm WARN deprecated nomnom@1.8.1: Package no longer supported. Contact support@npmjs.com for more info.
/apps/node-v10.11.0-linux-x64/bin/apidoc -> /apps/node-v10.11.0-linux-x64/lib/node_modules/apidoc/bin/apidoc
+ apidoc@0.17.6
added 42 packages from 25 contributors in 10.011s

从上面可以看出，apidoc被按照到了/apps/node-v10.11.0-linux-x64/bin目录下，为了便于使用，我们也创建一个软链接

2、创建软链接

[root@localhost apps]# ln -s /apps/node/bin/apidoc /usr/local/bin

3、查看帮助

[root@localhost apps]# apidoc -h

Usage: /apps/node-v10.11.0-linux-x64/bin/node apidoc [options]

Options:
   -f, --file-filters      RegEx-Filter to select files that should be parsed (multiple -f can be used).  [.*\.(clj|cls|coffee|cpp|cs|dart|erl|exs?|go|groovy|ino?|java|js|jsx|kt|litcoffee|lua|p|php?|pl|pm|py|rb|scala|ts|vue)$]
   -e, --exclude-filters   RegEx-Filter to select files / dirs that should not be parsed (many -e can be used).  []
   -i, --input             Input / source dirname.  [./]
   -o, --output            Output dirname.  [./doc/]
   -t, --template          Use template for output files.  [/apps/node-v10.11.0-linux-x64/lib/node_modules/apidoc/template/]
   -c, --config            Path to directory containing config file (apidoc.json)  [./]
   -p, --private           Include private APIs in output.  [false]
   -v, --verbose           Verbose debug output.  [false]
   -h, --help              Show this help information.
   --debug                 Show debug messages.  [false]
   --color                 Turn off log color.  [true]
   --parse                 Parse only the files and return the data, no file creation.  [false]
   --parse-filters         Optional user defined filters. Format name=filename
   --parse-languages       Optional user defined languages. Format name=filename
   --parse-parsers         Optional user defined parsers. Format name=filename
   --parse-workers         Optional user defined workers. Format name=filename
   --silent                Turn all output off.  [false]
   --simulate              Execute but not write any file.  [false]
   --markdown              Turn off default markdown parser or set a file to a custom parser.  [true]
   --line-ending           Turn off autodetect line-ending. Allowed values: LF, CR, CRLF.
   --encoding              Set the encoding of the source code. [utf8].  [utf8]

上面我们就按照好了apiDoc

三、使用apiDoc

1、首先创建一个项目目录

[root@localhost apps]# mkdir apidoc #在/apps目录下创建该目录
[root@localhost apps]# cd apidoc/ #进入到该目录

2、新建apidoc.json

[root@localhost apidoc]# vim apidoc.json #写入如下内容保存

{
  "name": "测试ApiDoc",
  "title": "测试API",
  "description":"测试API接口文档",
  "url" : "http://api.doc.com",
  "version": "1.0.0"
}

3、创建一个测试test.php

[root@localhost apidoc]# vim test.php #输入如下内容
<?php
/**
 *
 * @api {get} /getUserInfo/{id}
 * @apiDescription 获取用户信息接口描述
 * @apiGroup User
 * @apiName getUserInfo
 * @apiParam {Int} id 用户ID
 * @apiVersion 1.0.0
 *
 *
 * @apiExample {curl} 访问示例：
 * curl -i http://api.doc.com/getUserInfo/1
 *
 * @apiSuccess {String} success.
 */
function getUserInfo($id){
	return 'success';
}

上面的相关语法格式请参考apiDoc官网：http://apidocjs.com/

4、生成文档

[root@localhost apidoc]# apidoc -i ./ -o /apps/www/apidoc/test #-i表示输入的文件目录地址  -o表示输出的文件目录地址
[root@localhost apidoc]# ll /apps/www/apidoc/test/ #生成了如下文件
api_data.js       api_project.js    css/              img/              locales/          utils/            
api_data.json     api_project.json  fonts/            index.html        main.js           vendor/

5、配置nginx进行访问

#修改nginx.conf，在http里面新增一个server
server {
        listen       8080;
        server_name  localhost;
        root         /apps/www/apidoc/test; #刚刚生成的apidoc的目录

        location / {
           index index.html;
        }
}

保存后重启nginx，然后直接访问http://xxx.xxx.xxx.xxx:8080即可看到生成的文档。