前言
一直在等JFinal能用上Swagger UI的插件.. 然后看到JDoc,花了点时间整合, 虽然过程是坎坷的,但是结果还不错,生成的网页版文档超出了我的预期,希望JDoc发展的越来越好.
遇到的问题
目前JDoc还没发布到中央库,需要自己下载工程打包(折腾了好一会..)
1.1版本的JDoc添加了自动测试的功能(虽然我感觉用不上,还影响整合过程...)
项目是由Controller->Command->Service->Model.
Controller只是做个中转,具体的业务写在Command里,那么问题来了 这个文档注释写在Controller上就有点奇怪了..
写在Command上,文档生成的接口访问路径就不对了.
举个列子,下图所示.注释参数写在这里,有可能Command里修改了,Controller中给遗漏掉.
整合步骤
1.由于还不在中央库上,所以打包完放到工程中,本地引入
大概是因为jdoc-1.1.jar是本地引入的,Idea不会引用依赖,需要在pom.xml中加入依赖配置
<!-- JDoc文档生成 -->
<dependency>
<groupId>com.nmtx</groupId>
<artifactId>jdoc</artifactId>
<version>1.1</version>
<scope>system</scope>
<systemPath>${basedir}/lib/jdoc-1.1.jar</systemPath>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.9</version>
</dependency>
<dependency>
<groupId>freemarker</groupId>
<artifactId>freemarker</artifactId>
<version>2.3.9</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.4</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<version>3.1.0</version>
</dependency> 2.使用main方式手动生成api.html(这里不使用JDoc1.1自动测试的功能,个人觉得文档还是手动去更新生成好点,每次启动都生成一遍,略影响开发效率)
public class JDocMain {
public static void main(String[] args) {
new JFinalApiDocConfig("jdoc.properties").setClearSuffix("Controller").start();
}
}3.jdoc.properties配置
Idea与Eclipse不同的地方在于
Idea下如果有多个项目,则java.source=web名称/src/main/java.
Eclipse为java.source=src/main/java
#指定java文件路径 java.source=JFinalDubboDemoConsumer/src/main/java #指定需要生成文档的包路径 package.name=com.lastb7.dubbo.web #指定采用的框架类型,目前支持jfinal,springmvc两种框架 parser.name=jfinal #指定文档输出路径 out.path=JFinalDubboDemoConsumer/src/main/webapp/api.html #指定模版生成器，目前仅支持html parser.formater=html
4.接口注释
具体生成的规则看官方说明 JDoc 
效果图
项目链接
