REST开放接口生成文档工具之apidoc

一、安装node.js环境

感谢阿里云，下载的链接http://npm.taobao.org/mirrors/node/latest-v6.x/

二、安装apidoc

npm install apidoc -g

三、背景准备

1.以Java为例，新建一个java项目，假设名为test。

2.新建一个文本文件，命名apidoc.json，放置在test项目src根目录下。
3.新建一个Java文件，假设名为Test.java。

四、编写apidoc.json

这是在自动生成文档时的基础设置信息。

{
  "name": "apidoc-example",
  "version": "0.3.0",
  "description": "apiDoc example project",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1",
  "header": {
  "title": "My own header title",
  "filename": "header.md"
},
"footer": {
  "title": "My own footer title",
  "filename": "footer.md"
},
"order": [
  "GetUser",
  "PostUser"
],
"template": {
  "withCompare": true,
  "withGenerator": true
}
}

五、一个GET请求的示例

打开Test.java文件，在文件内写入以下注释。

/**
* @api {get} /pokka/:id pokka
* @apiName 获取指定Pokka
* @apiVersion 0.1.0
* @apiGroup Pokka
* @apiDescription 这是描述信息，可以有多行。
* @apiExample {curl} 接口示例: 
* curl -i http://localhost/pokka/4711
* @apiHeader {String} access-key 请求头必须携带字段access-key
* @apiHeaderExample {json} 头部示例: 
* { 
* "access-key": "按照约定加密方式产生的token==" 
* }
* 
* @apiSuccess (200) {String} firstname 姓氏
* @apiSuccess (200) {String} lastname 名称
* 
* @apiSuccessExample {json} 成功的响应: 
* HTTP/1.1 200 OK 
* {
* "firstname": "John", 
* "lastname": "Doe" 
* }
* 
*/

这些注释相对简单，能直观的看出来定义了

1. 接口格式（必选）
2. 接口名称
3. 接口版本
4. 接口所属组（必选）
5. 接口描述信息
6. 接口格式示例
7. 接口头定义
8. 接口头示例
9. 接口成功响应定义

六、接口成功响应示例

实际情况中，还会遇到携带参数的POST请求、错误的响应等等更多API描述需求。

更多的学习api地址：http://apidocjs.com/#params

七、最终的执行

命令格式为apidoc -i 项目实际目录 -o 希望输出到的目录

例如apidoc -i D:workspace est -o D:api-output

八、得到的结果

如果没有报错的话，进入D:api-output，双击index.html就可以看到漂亮的接口文档了。

例如此例得到的描述页面。