apidoc简单教程

在我们的项目开发过程中，经常涉及到api接口文档的编写，可是使用office工具编写的文档不够美观，现推荐一款好用的生成文档的工具-apidoc.

使用步骤:

1.安装nodejs。去http://www.nodejs.org/下载安装一个nodejs.

2.安装apidoc：命令行输入：npm install apidoc -g .

3.准备一个源码目录E:\apisrc，添加配置文件apidoc.json,内容如下：

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

相关参数按实际修改。

4.在源码目录E:\apisrc下，开发源码，例如使用java的源码company.java：

    /**
     * @api {get} /company/list 获取公司信息 
     * @apiName 获取公司列表 
     * @apiGroup All 
     * @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 分页数据对象数组 
     * @apiSuccessExample Success-Response: 
     *  HTTP/1.1 200 OK 
     * { 
     * code:0, 
     * msg:'success', 
     * data:{} 
     *  } 
     */  

源码目录如下：

5.生成api文档

apidoc -i E:\apisrc -o E:\apides

如果看到“info: Done.”说明生成成功 .

生成目录如下：

打开index.html查看生成的文档，效果图如下：

相关链接:
git地址：https://github.com/apidoc/apidoc
项目地址：http://apidocjs.com/
样例项目：http://apidocjs.com/example_basic/