标签:count ide str pig 大小 enum 小伙伴 默认 user
在后端开发过程中,接口文档的书写也是十分重要的,使用office软件自己编写出来的文档比较耗时,可以使用apidoc来在线生成接口文档。
一、下载安装nodejs,可以去官网下载https://nodejs.org/en/,安装过程直接点击下一步到完成即可。
二、到你的开发项目根目录下新建模板json,主要标识一些公共参数:apidoc.json,内容如下:
{
"name": "接口文档",
"version": "1.0.0",
"description": "小王的接口文档",
"title": "小王的接口文档",
"url" : "http://localhost:8070",
"sampleUrl":"http://localhost:8070"
}
三、使用注释的方式声明需要生成接口文档的数据,例如:
/** * @api {post} /code/index 测试接口 * @apiName 测试接口 * @apiGroup 测试 * @apiVersion 0.1.0 * @apiDescription 这是一个测试接口 * @apiParam {int} pageNum分页大小 * @apiSuccess {String} code 结果码 * @apiSuccess {String} msg 消息说明 * @apiSuccess {Object} data 分页数据封装 * @apiSuccess {int} data.count 总记录数 * @apiSuccess {Object[]} data.list 分页数据对象数组 * @apiSuccess {String} data.list.name 姓名 * @apiSuccess {String} data.list.sex 性别 */ @RequestMapping("/index") @ResponseBody public Object index(Integer pageNum) { // do something ...... }
需要注意的是@apiGroup默认是不兼容中文的,需要修改一下api_group.js文件里的代码,我的nodejs安装完之后是在C:\Users\Administrator\AppData\Roaming\npm\node_modules\apidoc\node_modules\apidoc-core\lib\workers这个目录。找到这一行group = group.replace(/[^\w]/g, ‘_‘);注释即可。
四、加上注释之后,cmd到项目根目录,运行apidoc可生成在线接口文档,可以跟参数-o 指定生成目录,然后将该目录nginx配置一下,你的小伙伴就可以在线访问了:)
效果如下:
五、必要的情况下注释参数(如@apiName等)的释义可以进一步查询学习。
标签:count ide str pig 大小 enum 小伙伴 默认 user
原文地址:https://www.cnblogs.com/mark8080/p/10366603.html