本文主要介绍API文档的自动生成——apidoc。网上有好几篇文章只介绍了apidoc，并没有介绍如何在自己的项目中使用以及如何与他人结合使用。最近开始玩服务器，了解到Windows和Linux之间有一种共享文件的方式，就是samba。那么结合apidoc使用起来就非常好用了，所以本文就记录为笔记_Apidoc介绍 apidoc是node的一个插件。它的作用是将我们的代码注释生成api文档。支持phpjavajavascriptpython等多种语言。因为写接口的同学通常会很烦恼写完接口还要写文档，文档更新又麻烦。apidoc不仅支持项目的版本，还支持API的版本。在我接触过的文档生成工具中，这是我觉得比较好用的一款。_apidoc安装 apidoc是node的一个插件，所以它的安装依赖于node。node的具体安装这里就不赘述了。去node官网下载包，解压，编译安装。直接执行：npminstallapidoc-g_sambainstallation samba的安装也很简单，我用的是CentOS，我直接执行yuminstallsamba就安装好了。_sambaconfiguration[public]comment=PublicStuffpath=/share/doc你需要分享的文件夹路径browseable=yesbrowsabilityguestok=yes是否允许访客public=yes是否上传writable=yes是否自己写它安装的时候也是这样配置的。注意这个samba需要你关闭你的防火墙，给你的共享目录赋予777的权限（好像755就够了，我直接给了777）。我这里也遇到了一个很坑爹的问题，就是这样配置的。当我使用Windows访问这个共享目录时，需要输入用户名和密码。其实主要是把上面的security=user改成security=sharesamba也支持用户管理，也就是可以分配账号密码，具体就不介绍了。_apidoc的使用 比如我们在代码里放这样的注释：/***@api{getpost}/brand/:id/:name/:new这里括号里填的是请求方法(GETPOSTOPTIONDELETE等)，后面是路由*@apiGroupbrandListAPI接口组名*@apiNamebrandsAPI接口名*@apiVersion1.0.1API接口版本*@apiDescriptionAPI接口描述**@apiParam(输入参数){Number{1-9999}}()是括号中的一组日期参数，同样的括号会放在id=0的同一个表中。请求参数大括号填入参数类型中的参数大括号表示取值范围后面是参数的名称和默认值*@apiParam(入参){String="a","b","c"}namebrandname，等号表示允许值*@apiParam(inputparameterParameter){Boolean}new*@apiParam(inputparameter){Number}[test]如果参数用方括号括起来像[],表示该值为可选值**@apiParamExample{json}接口返回值*{*"code":0,*"message":"success",*"data":{*"result":"ok"*}*}*@apiSampleRequest下面是模拟请求器，可以帮助我们调试接口*http://www.work.dev**/基本上用这些就够了，其他用法可以参考到它的官网：http://apidocjs.com/_generateapidoc 如果我在我的controller里面写了这样一条注释：/***@api{GET}/user_info获取用户信息接口*@apiGroupUser*@apiVersion2.0.0*@apiDescription获取用户信息**@apiParam(入口参数){String}token客户端登录成功后返回的token**@apiSuccessExampleSuccess-Response:*{*"code":0,*"message":"ok"*"data":{*"name":"1",//state0:enable1:disable*"role":"1",//1administrator,0为普通员工*"sex":"1",//1表示男，2表示女*}*}**@apiSampleRequest*http://api.test.com/user_info**/先cd进项目然后执行这样一条语句：apidoc-iapp/Http/Controllers-o\\115.28.231.211\public\因为我的samba共享了这么一个文件夹，而在这个里面放文件在其中，让我们看一下生成的结果。这个时候我们可以直接点击index.html看到这样一个静态页面：_下面的话 在这里，我们可以很方便的使用apidoc，我们可以在直接写界面的时候，直接写注释，写命令到启用了samba的服务器，然后直接访问静态页面。如果不想裸访问静态页面，可以直接用node或者nginx绑定，这里就不继续展开了。_后续补充 其实在使用的时候会发现一些很坑爹的问题，就是GroupName不能用中文，但是其他地方可以用中文。毕竟这是外国大佬发明的，不是中国人的产品，所以出现这样的问题在所难免。一直在找，发现github上有人给他提了issue。也给出了解决方法。apidoc的语法其实是支持引用的，所以我们可以定义/***@apiDefinenametestChinese*/然后我们怎么用。可以直接@apiUsename或者直接在注释里写name，这样就可以使用中文了。
