Centos下安装apiDoc和使用

xiaohai 2018-10-14 19:11:48 4163人围观 标签: apiDoc  工具 
简介apiDoc是一款可以有源代码中的注释直接自动生成api接口文档的工具,它几乎支持目前主流的所有风格的注释。例如: Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)

  在开发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即可看到生成的文档。