1.開發(fā)背景，這不重要
最近一直在寫dubbo接口，以前總是用word文檔寫接口描述然后發(fā)給別人。現(xiàn)在太多了，而且跟別人對接聯(lián)調(diào)的人家急著用，根本沒時間去寫word文檔。那就想想怎么用doc文檔注釋自動生成接口文檔了。本來以前對這一塊有點(diǎn)印象，但是并不熟悉，加上沒有很強(qiáng)烈的要去使用的意圖，所以一直沒有弄。今天要感謝公司的大神，大家都叫他歐神，神一樣的男人。讓我用文檔注釋。然后就知道怎么弄了，以下是生成的流程。
2.生成方法
先說生成的方法吧，免得一開始將注釋規(guī)范可能讀者覺得比較繁瑣，而且注釋規(guī)范基本上大家都有一套自己的做法。只要規(guī)范了注釋，就能輕易的生成注釋文檔。
2.1單擊project->Generate Javadoc出現(xiàn)如下界面
Javadoc command:執(zhí)行doc文檔注釋的命令，也可以在cmd窗口中輸入這個命令
Select types for which Javadoc will be generated:要生成文檔注釋的項(xiàng)目，這里選擇dubbo中間價項(xiàng)目，接口都在這里面聲明，生成的文檔自然就夠用了
Create Javadov for menbers with cisibility:選擇private就將私有屬性也生成到文檔中，默認(rèn)選擇的是public，建議選擇private
Destination:生成文檔路徑
2.2點(diǎn)擊下一步
這一頁的配置基本上全部選擇默認(rèn)，也可以根據(jù)自己的尿性勾選必要的東西
這里也可以導(dǎo)入自己的樣式文件，這樣可以讓文檔更美觀，這里省略
文檔標(biāo)題可以使用html，示例如下：
大數(shù)據(jù)接口Api
- Maven:
- <dependency>
- ? <groupId>api.jjshome.bigdata</groupId>
- ? <artifactId>bd-api-client</artifactId>
- ? <version>1.0.0-SNAPSHOT</version>
- </dependency>
2.3點(diǎn)擊下一步
這里要輸入自定義@標(biāo)簽的定義，如下：
-encoding?UTF-8?-charset?UTF-8?-tag?功能描述\::a:"功能描述"?-tag?項(xiàng)目名稱\::a:"項(xiàng)目名稱"?-tag?項(xiàng)目版本\::a:"項(xiàng)目版本"?-tag?使用對象\::a:"使用對象"?-tag?接口版本\::a:"接口版本"?-tag?創(chuàng)建作者\(yùn)::a:"創(chuàng)建作者"?-tag?創(chuàng)建日期\::a:"創(chuàng)建日期"?-tag?問題反饋\::a:"問題反饋";
當(dāng)然了，如果你全部用doc自帶的標(biāo)簽就不用輸入任何東西了。
2.4點(diǎn)擊完成
然后去2.1步驟中生成的doc路徑下打開index.html就可以看到doc文檔了，成果如下：
到這里就完成了生成的步驟了，下面我說一下一點(diǎn)點(diǎn)注釋要注意的地方,對于注釋規(guī)范的人可以不用看下去了，但是如果你生成的api里面基本上沒有什么內(nèi)容，那么建議你還是看看下面的內(nèi)容。
3.doc注釋
3.1多行注釋
對于屬性，方法，類的注釋必須使用多行注釋，單行注釋不會生成到文檔中
3.2屬性注釋：
/** 員工ID */
private String workerId;
3.3方法注釋：
/**
* @功能描述:
根據(jù)workerId查詢經(jīng)紀(jì)人小區(qū)帶看列表
*
注意：
* 只返回根據(jù)帶看數(shù)量，最近一次帶看時間倒序排序的前topNum條記錄
* @創(chuàng)建作者: **
* @創(chuàng)建日期: 2016年9月22日 下午3:11:46
* @param workerId 員工ID
* @param topNum 排序前幾個
* @return
返回對象參考{@link BigdataResult}<{@link List}<{@link AgentDKRecordVo}>>
*/
public BigdataResult> queryAgentDKList(String workerId, Integer topNum);
這里多使用注解就能生成漂亮的文檔了，參數(shù)和返回對象一定要寫清楚，如果有對象參數(shù)的話，就可以用@see注解，示例如下：
/**
* @功能描述: 根據(jù)workerId查詢經(jīng)紀(jì)人成交記錄
* @創(chuàng)建作者: **
* @創(chuàng)建日期: 2016年9月22日 下午8:49:02
* @param workerId 員工ID
* @param page 分頁對象
* @return
返回對象參考{@link BigdataResult}<{@link List}<{@link EsfCjHqHouseInfo}>>
* @see PageInfo
*/
public BigdataResult> queryEsfCjListByWorkerId(String workerId, PageInfo page);
這里的@see和@link都可以鏈接到指定對象的注釋文檔頁面，具體區(qū)別使用一次之后就一目了然了，同時@see和@link后面的對象也是需要導(dǎo)包的，不導(dǎo)包的話就使用全局限定名，如@see java.util.List
當(dāng)然，還可以加入自己定義的一些注解，這些注解要生成到文檔注釋中就要在如上圖的2.3步驟中聲明出來，如@功能描述
3.4類的注釋
/**
* @功能描述: 接口返回錯誤碼
* @項(xiàng)目版本: 1.0.0
* @項(xiàng)目名稱: 大數(shù)據(jù)接口中心
* @相對路徑: *.ResultCodeCenter.java
* @創(chuàng)建作者: **
* @問題反饋: **@126.com
* @創(chuàng)建日期: 2016年9月22日 下午2:32:53
*/
public class ResultCodeConstant {}
4注釋模板
單擊window->Preferences,搜索框輸入“Template”，就能看到模板設(shè)置的選項(xiàng)了，舉個栗子：
這里可以對屬性，方法，類，以及更多內(nèi)容做模板設(shè)置，這樣輸入注釋的時候就能統(tǒng)一了，而且免去了多打字的痛苦，上圖是一個類的注釋模板
有了這些基本上生成的接口文檔就夠用了，當(dāng)然。如果有更高的要求或者注釋有自己的規(guī)范，也可以按照自己的來設(shè)置更多內(nèi)容。
文末福利，關(guān)注我的公眾號：
后臺回復(fù)【視頻】：免費(fèi)獲取100G學(xué)習(xí)視頻
后臺回復(fù)【書籍真多】：免費(fèi)獲取超1000冊編程電子書資料
后臺回復(fù)【提問】：任何問題都可以問我，感謝支持。
