使用apidoc 生成Restful web Api文檔——新手問題與解決方法

使用apidoc工具來給項目做接口文檔，不僅有合理的源碼注釋，還可以生成對應的文檔。是給源碼寫備注的一個極佳實踐。

---

工具名稱：apiDoc 
Git地址：https://github.com/apidoc/apidoc 
項目地址：http://apidocjs.com/ 
樣例項目：http://apidocjs.com/example_basic/ 

博客學習：http://blog.csdn.net/soslinken/article/details/50468896

出現的問題：
 

1. 運行：apidoc -i test/ -o apidoc/，

　問題：提示 warn: Please create an apidoc.json configuration file.

　解決：在項目源碼文件夾創建 apidoc.json 文件

{
  "name": "測試",
  "version": "0.0.1",
  "description": "API文檔測試",
  "title": "API文檔測試",
  "url" : "http://xxxxxxx",
  "sampleUrl" : "http://xxxxxxxx",
  "template":{
    "forceLanguage":"zh-cn"
  }
}

 

2. 運行：apidoc -i test/ -o apidoc/，

　問題：提示如下錯誤

Block: 2,
Element: '@apiParam',
Source: '@apiParam {Number} 當前分頁.'


Block: 3,
Element: '@apiSuccess',
Source: '@apiSuccess {String} 新增博文頁面.'

　說明：@apiParam、@apiSuccess 等注解后面需要加上結果

　　　　使用規范：@apiSuccess [(group)] [{type}] field [description]

　解決：在文字前面加上與 field “返回字段的名稱” 對應的結果，沒有結果時寫 null 即可。

 

3. 運行：apidoc -i test/ -o apidoc/ 沒有報錯，得到結果

　問題：打開的界面只有loading，沒有顯示內容

　說明：在查找很多相關內容之后，有可能的結果是說配置文件中的version需要和apidoc對應，結果刪除了也不行。后面把配置文件修改成最初狀態，正常導出API文檔。

　解決：將apidoc.json文件修改成如上的默認狀態，重新生成即可完成