API文档自动生成

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

apidoc简介

　　apidoc是node的一个插件，它的功能就是能让把咱们的代码注释生成api文档。它支持php java javascript python等多中语言。由于写接口的同窗一般很烦写完接口还得写文档，文档更新又麻烦。apidoc不只支持项目的版本，也支持api的版本。在我所接触过的文档生成工具里面，这个是我感受比较好用的。
_

apidoc的安装

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

npm install apidoc -g

_

samba的安装

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

yum install samba

就安装好了。
_

samba的配置

[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的使用

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

/**
 * @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
 *
 */

基本上用这些已经足够了，其余的用法能够参考它的官网:http://apidocjs.com/
_

生成apidoc

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

/**
* @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到项目里面
而后执行这样的语句:

apidoc -i app/Http/Controllers -o \\115.28.231.211\public\

由于我samba共享的是这样一个文件夹，而且在这个里面放文档。而后咱们来看下生成的结果

这时候咱们直接点击index.html能够直接看到这样的静态页面:

_

后话

　　到这里，咱们就已经很方便的能运用apidoc了，咱们能够本身直接写好接口的时候直接写注释，一句命令写到开了samba的服务器上，而后直接访问静态页面，若是不想这样赤裸裸的访问静态页面，能够用node或者nginx直接绑上去，这里就不继续展开讲了。
_

后续补充

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

/**
 * @apiDefine name 测试中文
 */

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

　　<font color='red'>这个东西惟一让我不爽的就是有可能一大段注释只是为了生成接口文档！！！其它真的很好用</font>