码迷,mamicode.com
首页 > Windows程序 > 详细

apidoc使用记录

时间:2019-02-12 18:48:14      阅读:291      评论:0      收藏:0      [点我收藏+]

标签: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等)的释义可以进一步查询学习。

apidoc使用记录

标签:count   ide   str   pig   大小   enum   小伙伴   默认   user   

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

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!