java生成API文檔

最近想要對java項目自動生成API文檔，發現一個工具apidoc。這個工具可以依據一定格式的註釋生成相應的HTML格式API接口文檔，具體可以參考apidoc的官網。

使用方法如下：

1. 安裝命令

   npm install apidoc -g
   

2. 生成文檔命令

   apidoc -i myapp/ -o apidoc/ 
   

   myapp是項目的文件夾，需要包含apidoc.json，以及含有接口註釋的源碼文件。apidoc是生成的HTML的存放文件夾。

3. apidoc.json文件

   {
     "name": "xxx項目",
     "version": "1.0.0",
     "description": "api文檔",
     "title": "api文檔",
     "url" : "http://127.0.0.1:8080",
     "sampleUrl":"http://127.0.0.1:8080"
   }
   

4. 生成的HTML如下
   

由此上的步驟便可以生成HTML格式的API文檔。

同時也有一款能將apidoc的HTML轉爲Markdown文檔，地址https://github.com/rigwild/apidoc-markdown

但是，如果手動輸入註釋未免過於麻煩。於是我在IDEA上發現了一個生成apido註釋的插件apiDoc。
該插件的源碼地址https://gitee.com/UnlimitedBladeWorks_123/apidoc-plugin-idea。

使用方法如下：

1. 在IDEA上安裝apiDoc插件。在Plugins中搜索apiDoc，選擇安裝(我這裏已經安裝完了)

2. 在方法名稱上右鍵選擇apiDoc

3. 生成註解，插件會依據實體（以及實體屬性註釋）生成註解。

4. 生成的註釋內容

   /**
    * @api {POST} /department/updateDepartment updateDepartment
    * @apiVersion 1.0.0
    * @apiGroup DepartmentController
    * @apiName updateDepartment
    * @apiDescription 更新部門信息
    * @apiParam (請求參數) {Number} depId 部門Id
    * @apiParam (請求參數) {String} depName 部門名稱
    * @apiParamExample 請求參數示例
    * depId=8670
    * depName=zVppqCv
    *
    * @apiSuccess (響應結果) {Number} code 狀態碼
    * @apiSuccess (響應結果) {String} msg 狀態信息
    * @apiSuccess (響應結果) {Object} data 返回數據
    * @apiSuccessExample 響應結果示例
    * {"msg":"wm","code":2427,"data":{}}
    */