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就可以看到漂亮的接口文檔了。

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