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\test -o D:\api-output

八、得到的结果

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

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

巴特西

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

最新文章

热门文章