使用【APIDOC】生成JavaWeb的API文件（HTML，MarkDown，PDF）

目前流行的框架是前後端分離,頁面之間的跳轉由前端負責,後端主要是進行資料處理和API的提供,之前寫文件都是通過手寫的方式,發現這種方式效率非常的低下,為啥不考慮使用生成器生成呢?

1. APIDOC的安裝

apidoc是一個可以直接由原始碼中滴注釋生成api介面文件的自動化文件匯出工具，並且支援目前流行的幾乎所有格式的註釋風格。該工具的原始碼目前託管於github(https://github.com/apidoc/apidoc)

使用apidoc必須要安裝node環境，安裝好npm之後。

 npm install apidoc -g

2. 程式碼註釋遵循apidoc風格

既然要使用apidoc匯出文件，那自然要讓apidoc認識你的註釋，apidoc註釋規範可以參考官方文件(http://apidocjs.com)

  /**
     * @api {get} /test 介面測試
     * @apiDescription 根據ID（id）獲取列表資訊
     * @apiGroup test APIs
     *
     * @apiParam {Number} id 任務ID
     * @apiParam {Number} [page] 頁數
     * @apiParam {Number} [perpage] 每頁的條數
     *
     * @apiParamExample {string} 請求引數格式:
     *    ?id=123&page=1&perpage=20
     *
     * @apiVersion 1.0.0
     * @apiErrorExample {json} 錯誤返回值:
     *     {
     *        "code": 10003,
     *        "msg": "ParametersError [Method]:get_tests引數錯誤!",
     *        "error": {
     *            "id": "",
     *            "page": "",
     *            "perpage": ""
     *        },
     *       "status": "fail"
     *     }
     * @apiSuccessExample {json} 正確返回值:
     *     {
     *   "code": 0,
     *   "msg": "OK ",
     *   "data": [
     *       {
     *           "id": "622051004185471233",
     *           "testCode": "000050",
     *       }
     *   ],
     *   "status": "ok",
     *   "count": "14"
     *   }
     */
    @RequestMapping(value = "listxcx")
    @ResponseBody
    public Map<String,Object> listSmallProgram() {
        return null;
    }

3. 執行apidoc 匯出HTML文件

執行apidoc前需要先新增一個配置檔案apidoc.json,該配置檔案的內容官方文件裡有介紹，大致如下：

{
  "name": "理可實驗室",
  "version": "0.1.0",
  "description": "理可的實驗室",
  "title": "理可的實驗室",
  "url" : "http://btcbei.com/"
}

匯出命令:

  apidoc -i 你的專案檔案目錄/ -o 輸出檔案目錄/

匯出結果:

4. 匯出為Markdown的格式

apidoc所做的工作主要是通過讀取原始碼中的註釋，解析生成一個api_data.json檔案和api_project.json，這個檔案裡面包含了所有從註釋中提取粗來的介面資料。所以接下來的工作便是根據這個api_data.json檔案和api_project.json生成markdown檔案即可。

安裝apidoc-markdown

npm install  apidoc-markdown -g

匯出markdown

apidoc-markdown -p apidoc_dir -o doc/doc_markdown.md

匯出結果:

5. 匯出為pdf

既然markdown檔案都有了，那麼匯出PDF檔案不是更簡單了。在這裡，推薦一個灰常好用的markdown離線編輯工具——Typora

6.總結

以後麻麻再也不用擔心我寫介面文件啦！