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>&lt;dependency&gt;</li><li>&nbsp;&nbsp;&lt;groupId&gt;com.ex.api&lt;/groupId&gt;</li><li>&nbsp;&nbsp;&lt;artifactId&gt;ex-api-demo&lt;/artifactId&gt;</li><li>&nbsp;&nbsp;&lt;version&gt;1.0.0-SNAPSHOT&lt;/version&gt;</li><li>&lt;/dependency&gt;</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

注释生成Api文档的更多相关文章

  1. .Net魔法堂:提取注释生成API文档

    一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和减少后期维护中知识遗失等风险 ...

  2. 使用sphinx快速为你python注释生成API文档

    sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...

  3. .net 提取注释生成API文档 帮助文档

    提取注释生成API文档   一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和 ...

  4. 试试使用 eolinker 扫描 GitLab 代码注释自动生成 API 文档?

    前言: 一般写完代码之后,还要将各类参数注解写入API文档,方便后续进行对接和测试,这个过程通常都很麻烦,如果有工具可以读取代码注释直接生成API文档的话,那会十分方便. 此前一直都是在使用eolin ...

  5. 利用sphinx为python项目生成API文档

    sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤 1:安装 pip install -U Sphinx 2:在需要生成文档的.py文件目录下执行sphinx-apido ...

  6. 自动生成api文档

    vs2010代码注释自动生成api文档 最近做了一些接口,提供其他人调用,要写个api文档,可是我想代码注释已经写了说明,能不能直接把代码注释生成api?于是找到以下方法 环境:vs2010 先下载安 ...

  7. eclipse中javadoc给项目生成api文档

    步骤 1.打开java代码,编写JavaDoc 注释,只有按照java的规范编写注释,才能很好的生成API文档,javadoc注释与普通注释的区别为多一个*(星号).普通代码注释为/*XXX*/,而j ...

  8. 12 Django Rest Swagger生成api文档

    01-简介 Swagger:是一个规范和完整的框架,用于生成.描述.调用和可视化RESTful风格的Web服务.总体目标是使客户端和文件系统源代码作为服务器以同样的速度来更新.当接口有变动时,对应的接 ...

  9. 如何利用showdoc自动生成API文档

    介绍 showdoc是一个适合IT团队的文档工具,阅读本文前需要对showdoc有基本了解 .基本介绍可看:https://www.showdoc.cc/help 对于写API文档这件事,虽然说文本编 ...

随机推荐

  1. Angular2入门系列教程4-服务

    上一篇文章 Angular2入门系列教程-多个组件,主从关系 在编程中,我们通常会将数据提供单独分离出来,以免在编写程序的过程中反复复制粘贴数据请求的代码 Angular2中提供了依赖注入的概念,使得 ...

  2. FreeMarker:怎么使用

    第一个FreeMarker程序 1. 建立一个普通的java项目:testFreeMarker 2. 引入freemarker.jar包 3. 在项目目录下建立模板目录:templates 4. 在t ...

  3. 一个简单的网站web项目的详解

    有不对的术语,或者不好理解的部分,欢迎大家批评指正,谢谢大家! 近期做的网站web项目,实现登录功能,查询功能.首先把这个项目分为几个模块来处理,当前用户模块,历史用户模块,历史记录模块,数据库模块, ...

  4. CentOS 7 安装出现 /dev/root does not exits 导致无法安装的问题

    本人在官网下的是这个 CentOS-7-x86_64-DVD-1611.iso ,然后用UltraISO 9.6制作的U盘启动盘,不过在安装的时候出现了这个错误, 然后也是搜了好久,试了一下,下面这个 ...

  5. 安装devtoolset

    在运维的工作内,经常要编译安装各种开源组件,以CentOS 6的用户来说,大部分时候用到gcc的时候都是4.4.7版本的,在绝大多数情况下编译一些东西还是够用的,但还是有个别软件对gcc的版本是有要求 ...

  6. windows 2012 r2 can't find kb2919355

    问题   解决: 1.手动安装了 Windows8.1-KB2919442-x64 2.手动下载 KB2919355 更新成功     Turns out to have been a result ...

  7. SpringMVC 数据校验

    1.引入jar包 2.配置验证器 <!-- 配置验证器 --> <bean id="myvalidator" class="org.springfram ...

  8. Jenkins配置MSBuild实现自动部署(MSBuild+SVN/Subversion+FTP+BAT)

    所要用到的主要插件: [MSBuild Plugin] 具体操作: 1.配置MSBuild的版本 [系统管理]->[Global Tool Configuration]->[MSBuild ...

  9. 学习笔记:7z在delphi的应用

    最近做个发邮件的功能,需要将日志文件通过邮件发送回来用于分析,但是日志文件可能会超级大,测算下来一天可能会有800M的大小.所以压缩是不可避免了,delphi中的默认压缩算法整了半天不太好使,就看了看 ...

  10. Retrofit2.0起步篇

    retrofit 英文名字是改装的意思,也就是说他是对网络请求的一种改装,他不负责进行网络请求,他是对请求方式的一种封装.真正进行网络请求的是okhttp. 以下所有内容在Android Studio ...