apidoc使用记录

Posted 2021-02-09 王凯的编码日志

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