新公司注册在哪个网站,手机网站一键开发,江苏建设网官网,wordpress 神箭手本文主要讲述自动化API文档生成——apidoc。网上有几个篇文章都只是介绍apidoc的#xff0c;具体怎么在自己的项目中使用以及与其他配合使用都是没介绍的。最近开始玩服务器#xff0c;了解到了有Windows与Linux之间共享文件的方法#xff0c;就是samba。然后具体和apidoc结… 本文主要讲述自动化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 Stuffpath /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}}()这个括号里面的天的参数的组括号里面相同的会被放在同一个表格里面 id0 请求参数 大括号里面填的是参数类型 里面的大括号表示值的范围 后面就是参数的名称和默认值* apiParam (入参) {Stringa,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 colorred这个东西唯一让我不爽的就是有可能一大段注释只是为了生成接口文档其它真的很好用/font
