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屬性注釋：
/** 員工ID */
private String workerId;
3.3方法注釋：
/**
* @功能描述: <p>根據workerId查詢經紀人小區帶看列表</p>
* <p><font color=red>注意：</font>
* 只返回根據帶看數量，最近一次帶看時間倒序排序的前topNum條記錄</p>
* @創建作者: **
* @創建日期: 2016年9月22日 下午3:11:46
* @param workerId 員工ID
* @param topNum 排序前幾個
* @return <p>返回對象參考{@link BigdataResult}<{@link List}<{@link AgentDKRecordVo}>></p>
*/
public BigdataResult<List<AgentDKRecordVo>> queryAgentDKList(String workerId, Integer topNum);
這里多使用注解就能生成漂亮的文檔了，參數和返回對象一定要寫清楚，如果有對象參數的話，就可以用@see注解，示例如下：
/**
* @功能描述: 根據workerId查詢經紀人成交記錄
* @創建作者: **
* @創建日期: 2016年9月22日 下午8:49:02
* @param workerId 員工ID
* @param page 分頁對象
* @return <p>返回對象參考{@link BigdataResult}<{@link List}<{@link EsfCjHqHouseInfo}>></p>
* @see PageInfo
*/
public BigdataResult<List<EsfCjHqHouseInfo>> queryEsfCjListByWorkerId(String workerId, PageInfo page);
這里的@see和@link都可以鏈接到指定對象的注釋文檔頁面，具體區別使用一次之后就一目了然了，同時@see和@link后面的對象也是需要導包的，不導包的話就使用全局限定名，如@see java.util.List
當然，還可以加入自己定義的一些注解，這些注解要生成到文檔注釋中就要在如上圖的2.3步驟中聲明出來，如@功能描述
3.4類的注釋
/**
* @功能描述: 接口返回錯誤碼
* @項目版本: 1.0.0
* @項目名稱: 大數據接口中心
* @相對路徑: *.ResultCodeCenter.java
* @創建作者: **
* @問題反饋: **@126.com
* @創建日期: 2016年9月22日 下午2:32:53
*/
public class ResultCodeConstant {}
4注釋模板
單擊window->Preferences,搜索框輸入“Template”，就能看到模板設置的選項了，舉個栗子：
這里可以對屬性，方法，類，以及更多內容做模板設置，這樣輸入注釋的時候就能統一了，而且免去了多打字的痛苦，上圖是一個類的注釋模板
有了這些基本上生成的接口文檔就夠用了，當然。如果有更高的要求或者注釋有自己的規范，也可以按照自己的來設置更多內容。
僅供參考，不足之處還請見諒，歡迎指正！轉載請標明出處。如有疑問，歡迎評論或者聯系我郵箱
1034570286@qq.com