在后端开发过程中，接口文档的书写也是十分重要的，使用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等）的释义可以进一步查询学习。

apidoc使用记录

标签：

原文地址：https://www.cnblogs.com/mark8080/p/10366603.html