apiDoc自動生成api文檔

在自定生成api文檔方面以前都是使用swagger.json結合swagger工具來生成文檔，偶然發現了apidoc這個生成api的工具，發現使用起來比swagger更加簡單，下面整理一下使用過程：

1、安裝

首先通過npm全局安裝apidoc

$ npm install apidoc -g

2、使用

使用的時候最主要是參考官方文檔 ，apidoc文檔，文檔中清晰的記錄了怎么使用的過程，最好也要看一下apidoc的github地址，從哪里你可以看到一個簡單的example，

下面就是利用github上apidoc的example來作為實例，example的結構如下：

weifandeMacBook-Pro:example weifan$ ls
_apidoc.js    apidoc.json    example.js    footer.md    header.md

3、生成api文檔

首先我們在執行apidoc命令的目錄下，新建一個apiDocs文件，命令如下：

mkdir apiDocs

然后執行生成api文檔命令，如下：

$ apidoc -i example/ -o apiDocs/

其中apidoc 參數如下：

• -i
  讀取用於生成文檔的目錄，比如src目錄
• -o
  生成api文檔靜態頁面的目錄
• -t
  自定義的模板目錄，默認使用apiDoc的模板
• -f “.*\.java$”
  解析符合正則表達式的文件
• -h
  顯示幫助信息

在你運行上面命令的時候如果example文件夾下沒有apidoc.json這個文件，則會出現一下警告信息：

warn: Please create an apidoc.json configuration file.
info: Done.

說明你沒有配置生成api的配置文件（如果沒有其實也是可以生成的只不過是默認格式）。

此時你會看到apiDocs文件夾下回有生成的index.html文件，在瀏覽器中運行這個文件，你就會看到你生成的api文檔了。

5、配置 apidoc.json

在執行 apidoc 命令的目錄執行創建apidoc.json文件，並加入以下內容：

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

• name
  文檔內容的最大標題
• version
  文檔的版本號，一般保持在最新
• description
  文檔的描述
• title
  顯示網頁的title
• url
  每個api地址前綴
• sampleUrl
  請求示例工具的地址前綴，當有此項時，會出現該工具
• header/footer
  文檔的頭部和尾部
  • title
    頭/尾部標題
  • filename
    頭部markdown文件
• template
  • withCompare
    自動生成版本比較功能的文件，默認 true
  • withGenerator
    生成默認的apidoc版權，默認 true

6、apiDoc 注解

下面是apidoc的注解，最主要還是要參照官方文檔。

• @api {method} path [title]
  method 請求方式: get/post/put…
  path User/register
  title 標題
• @apiDescription text
  api描述
• @apiError [(group)] [{type}] field [description]
• @apiErrorExample [{type}] [title]
  example
• @apiExample [{type}] title
  example
• @apiGroup name
• @apiHeader [(group)] [{type}] [field=defaultValue] [description]
• @apiHeaderExample [{type}] [title]
  example
• @apiIgnore [hint]
• @apiName name
• @apiParam [(group)] [{type}] [field=defaultValue] [description]
• @apiParamExample [{type}] [title]
  example
• @apiPermission name
• @apiSampleRequest url
• @apiSuccess [(group)] [{type}] field [description]
• @apiSuccessExample [{type}] [title]
  example
• @apiUse name
• @apiVersion version

問題

1. 無法生成帶有歷史版本比較功能
   必須同時加上 @apiVersion @apiName @apiGroup 這個三個注解
2. @apiName后面不要使用中文介紹，必須要使用英文，不然這個api可能會被隱藏。詳見：https://github.com/apidoc/apidoc/issues/431
3. 最好不要包含一些特殊字符，特殊字符可能會導致編譯有問題

參考

官方文檔: http://apidocjs.com
官方示例: https://github.com/apidoc/apidoc/tree/master/example