apiDoc是一款用来生成接口文档的工具,非常容易上手,而成生成的接口文档为网页版,简洁美观。
学习任何技术最好的方式就是去看官网,所以先列出apdDoc的官网地址:http://apidocjs.com/。
第一步,安装。(本文中只介绍的是在windows环境下)
确保本机上已经安装node.js,安装后在命令框中输入:
npm install apidoc -g
安装后,使用apidoc -h命令测试是否安装成功。
第二步,关于配置文件的编写。
首先在你的项目的根目录下新建apidoc.json文件,该文件描述了项目对外提供接口的概要信息如名称、版本、描述、
文档打开时浏览器显示标题和接口缺省访问地址。
{
"name": "GeoService服务API",
"version": "0.1.0",
"description": "V0.1.0 GeoService服务API",
"title": "GeoService服务API",
"url" : "http://geos.cn/api/",
"template": {
"withCompare": true,
"withGenerator": true
}
}
然后在该目录中创建一个objec.java文件,用来描述接口地址,参数等信息,样例如下:
/**
* @api {get} /hello 测试接口
* @apiVersion 0.1.0
* @apiName hello
* @apiGroup GeoService
*
* @apiDescription 测试服务是否启动
*
*
*@apiSuccessExample Success-Response:
*{
"Hello Geo-SERVICE !"
}
*
*/
第三步,生成接口文档,命令如下:
apidoc -i myapp/ -o apidoc/
其中,myapp为存放配置文件的路径,apidoc为要输出的接口文档的地址路径