apiDoc

大家所熟知的API文档有swagger等, 今天给大家推荐一个写注释就能生成文档的工具, 真的很简单! http://apidocjs.com/

快速开始

第一步 安装node.js

第二步 执行安装命令

版本0.26.0

npm install apidoc@0.26.0 -g

第三步 新建一个项目

src: 打算放注释文档的文件, 先只建一个文件(file1.js, 不用纠结这些注释含义, 后面会详解)代码如下

/**
     * @api {post} /vote/prize_list 查看获奖名单
     * @apiVersion 0.1.0
     * @apiName prize_list
     * @apiGroup vote
     *
     * @apiParam {String} openid *openid
	 * @apiParam {String} activity_id *activity_id
     * @apiSuccessExample 请求成功:
     *     HTTP/1.1 200 OK
     *          {
     *              'code' => 'success',
     *              'msg' => $msg,
     *              'data' => {
     *                        }
     *       }
     *
     *
     * @apiErrorExample 404失败原因:
     *     HTTP/1.1 404 Not Found
     *     {
     *        'code' => 'fail',
     *        'msg' => $msg,
     *        'data' => $data,
     *     }
     *
     * @apiSampleRequest https://www.baidu.com/vote/prize_list
     */

apidoc.json: 文档配置文件, 示例代码如下.

{
  "name": "智造阶",
  "version": "0.1.0",
  "description": "智造阶平台API文档",
  "title": "智造阶",
  "url" : "https://www.baidu.com"
}

第四步 执行命令. -i是指注释文件存放的地方, -o是指文档输出的位置

apidoc -i src/ -o apidoc/

接下来我们会发现多了一个文件夹apidoc. 这是自动生成的一个文件夹目录

里面放的就是API文档, 里面有一个index.html, 我们双击打开.

这3个部分眼熟么? 没错! 这就是我们一开始定义的apidoc.json里面的配置文件. 简单三步即可生成一份API文档, 算是挺傻瓜式的了.