注释生成Api文档
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
