python⽣成api⽂档_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接⼝的描述
*
python中文文档
* @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 下⾯就是⼀个模拟请求器，可以帮我们调试接⼝
*
*/
_
⽣成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
*
*/
先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，这样就可以使⽤中⽂了。这个东西唯⼀让我不爽的就是有可能⼀⼤段注释只是为了⽣成接⼝⽂档其它真的很好⽤

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。