1.開發背景 最近一直在寫dubbo接口，以前總是用word文檔寫接口描述然後發給别人。現在太多了，而且跟别人對接聯調的人家急着用，根本沒時間去寫word文檔。那就想想怎麼用doc文檔注釋自動生成接口文檔了。本來以前對這一塊有點印象，但是并不熟悉，加上沒有很強烈的要去使用的意圖，是以一直沒有弄。今天要感謝公司的大神，大家都叫他歐神，神一樣的男人。讓我用文檔注釋。然後就知道怎麼弄了，以下是生成的流程。 2.生成方法 先說生成的方法吧，免得一開始将注釋規範可能讀者覺得比較繁瑣，而且注釋規範基本上大家都有一套自己的做法。隻要規範了注釋，就能輕易的生成注釋文檔。 2.1單擊project->Generate Javadoc出現如下界面
Javadoc command:執行doc文檔注釋的指令，也可以在cmd視窗中輸入這個指令 Select types for which Javadoc will be generated:要生成文檔注釋的項目，這裡選擇dubbo中間價項目，接口都在這裡面聲明，生成的文檔自然就夠用了 Create Javadov for menbers with cisibility:選擇private就将私有屬性也生成到文檔中，預設選擇的是public，建議選擇private Destination:生成文檔路徑 2.2點選下一步 這一頁的配置基本上全部選擇預設，也可以根據自己的尿性勾選必要的東西 這裡也可以導入自己的樣式檔案，這樣可以讓文檔更美觀，這裡省略 文檔标題可以使用html，示例如下： 接口Api <h2><ul><li>Maven:</li><li><dependency></li><li> <groupId>com.ex.api</groupId></li><li> <artifactId>ex-api-demo</artifactId></li><li> <version>1.0.0-SNAPSHOT</version></li><li></dependency></li></ul></h2> 2.3點選下一步 這裡要輸入自定義@标簽的定義，如下： -encoding UTF-8 -charset UTF-8 -tag 功能描述\::a:"功能描述" -tag 項目名稱\::a:"項目名稱" -tag 項目版本\::a:"項目版本" -tag 建立作者\::a:"建立作者" -tag 建立日期\::a:"建立日期" -tag 問題回報\::a:"問題回報" 當然了，如果你全部用doc自帶的标簽就不用輸入任何東西了。 2.4點選完成 然後去2.1步驟中生成的doc路徑下打開index.html就可以看到doc文檔了，成果如下：
到這裡就完成了生成的步驟了，下面我說一下一點點注釋要注意的地方,對于注釋規範的人可以不用看下去了，但是如果你生成的api裡面基本上沒有什麼内容，那麼建議你還是看看下面的内容。 3.doc注釋 3.1多行注釋 對于屬性，方法，類的注釋必須使用多行注釋，單行注釋不會生成到文檔中 3.2屬性注釋： private String workerId; 3.3方法注釋： public BigdataResult<List<AgentDKRecordVo>> queryAgentDKList(String workerId, Integer topNum); 這裡多使用注解就能生成漂亮的文檔了，參數和傳回對象一定要寫清楚，如果有對象參數的話，就可以用@see注解，示例如下： public BigdataResult<List<EsfCjHqHouseInfo>> queryEsfCjListByWorkerId(String workerId, PageInfo page); 這裡的@see和@link都可以連結到指定對象的注釋文檔頁面，具體差別使用一次之後就一目了然了，同時@see和@link後面的對象也是需要導包的，不導包的話就使用全局限定名，如@see java.util.List 當然，還可以加入自己定義的一些注解，這些注解要生成到文檔注釋中就要在如上圖的2.3步驟中聲明出來，如@功能描述 3.4類的注釋 public class ResultCodeConstant {} 4注釋模闆 單擊window->Preferences,搜尋框輸入“Template”，就能看到模闆設定的選項了，舉個栗子：
這裡可以對屬性，方法，類，以及更多内容做模闆設定，這樣輸入注釋的時候就能統一了，而且免去了多打字的痛苦，上圖是一個類的注釋模闆 有了這些基本上生成的接口文檔就夠用了，當然。如果有更高的要求或者注釋有自己的規範，也可以按照自己的來設定更多内容。 僅供參考，不足之處還請見諒，歡迎指正！轉載請标明出處。如有疑問，歡迎評論或者聯系我郵箱 [email protected]
轉載于:https://www.cnblogs.com/itechpark/p/yinzei_doc_api.html