前言

        一直在等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       

效果图

项目链接

      git地址