本文主要讲述自动化API文档生成——apidoc。网上有几个篇文章都只是介绍apidoc的,具体怎么在自己的项目中使用以及与其他配合使用都是没介绍的。最近开始玩服务器,了解到了有Windows与Linux之间共享文件的方法,就是samba。然后具体和apidoc结合起来非常好用,所以本文就当做笔记来把它记录下来了

apidoc简介

apidoc是node的一个插件,它的功能就是能让把我们的代码注释生成api文档。它支持php java javascript python等多种语言。因为写接口的同学通常很烦写完接口还得写文档,文档更新又麻烦。apidoc不仅支持项目的版本,也支持api的版本。在我所接触过的文档生成工具里面,这个是我感觉比较好用的。


apidoc的安装

apidoc是node的一个插件,那么它的安装就依赖node。node的具体安装我这里就不详细说了,去node官网下包,解压,编译然后安装。直接执行:

1
npm install apidoc -g


samba的安装

samba的安装也很简单,本人用的是CentOS,我直接执行:

1
yum install samba

就安装好了


samba的配置

1
2
3
4
5
6
7
[public]
comment = Public Stuff
path = /share/doc //你需要共享文件夹的路径
browseable = yes //可浏览性
guest ok = yes //是否允许访客
public = yes //是否可上传
writable = yes //是否可写

我自己装的时候也都是这么配置的,注意,这个samba需要你关闭你的防火墙,还得把你共享的目录赋予777的权限(貌似755就够了,我直接给了777)。我这边还遇到过一个很坑爹的问题,就是这样配置了,用Windows访问这个共享目录的时候,要求我输入用户名和密码。其实主要还得把上面的
security = user
改成
security = share

samba也是支持用户管理的,就是可以分配账号密码的,具体的就不展开介绍了。


apidoc的使用

  例如我们在代码里面下了这样的一段注释:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/**
* @api {get post}; /brand/:id/:name/:new 这里中括号里面填的的是请求方式(GET POST OPTION DELETE等),后面填的是路由
* @apiGroup brandList API接口所在的组名称
* @apiName brands API接口名称
* @apiVersion 1.0.1 API接口版本
* @apiDescription API接口的描述
* @apiParam (入参) {Number{1-9999}}()这个括号里面的填的参数的组,括号里面相同的会被放在同一个表格里面 id=0 请求参数 大括号里面填的是参数类型 里面的大括号表示值的范围 后面就是参数的名称和默认值
* @apiParam (入参) {String=“a”,“b”,“c”}; name 品牌名称,等于号表示允许值
* @apiParam (入参) {Boolean}; new
* @apiParam (入参) {Number} [test] 如果参数套上[]这样的中括号,表明这个值是个可选的值
*
* @apiParamExample {json} 接口返回值
* {
* “code” : 0,
* “message” : “success”,
* “data” : {
* “result” : “ok”;
* }
* }
* @apiSampleRequest 下面就是一个模拟请求器,可以帮我们调试接口
* http://www.work.dev
*/

基本上用这些已经足够了,其他的用法可以参考它的官网:

生成apidoc

假如我在我的控制器里面写了这样一段注释:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/**
* @api {GET} /user_info 获取用户信息接口
* @apiGroup User
* @apiVersion 2.0.0
* @apiDescription 获取用户信息
*
* @apiParam (入参) {String} token 登录成功后客户端返回的token
*
* @apiSuccessExample Success-Response:
* {
* "code": 0,
* "message": "ok"
* "data": {
* "name": "1",//状态 0:启用 1:停用
* "role": "1",//1管理员,0是普通员工
* "sex": "1",//1表示男性,2表示女性
* }
* }
*
* @apiSampleRequest
* http://api.test.com/user_info
*
*/

先cd到项目里面
然后执行这样的语句:

1
apidoc -i app/Http/Controllers -o \\xxx.xxx.xxx.xxx\public\

因为我samba共享的是这样一个文件夹,并且在这个里面放文档。然后我们来看下生成的结果:
apidoc生成的结果

这时候我们直接点击index.html可以直接看到这样的静态页面:

打开页面结果


后话

到这里,我们就已经很方便的能运用apidoc了,我们可以自己直接写好接口的时候直接写注释,一句命令写到开了samba的服务器上,然后直接访问静态页面,如果不想这样赤裸裸的访问静态页面,可以用node或者nginx直接绑上去,这里就不继续展开讲了


后续补充

其实在使用中的时候会发现一些很坑爹的问题,就是GroupName没法用中文,但是其他地方可以用中文。毕竟这个是国外大佬发明的,不是国人的产物,有存在这样的问题也在所难免。我不断的搜,发现github上有人给他提issure。也有给出了解决方案,apidoc的语法其实是支持引用的,所以我们可以这样定义

1
2
3
/**
* @apiDefine name 测试中文
*/

然后我们怎么使用呢。可以直接@apiUse name也可以直接在注释里面写name,这样就可以使用中文了。