JFinal3.0整合JDoc1.1生成文档

前言

        一直在等JFinal能用上Swagger UI的插件.. 然后看到JDoc,花了点时间整合, 虽然过程是坎坷的,但是结果还不错,生成的网页版文档超出了我的预期,希望JDoc发展的越来越好.

遇到的问题

        目前JDoc还没发布到中央库,需要自己下载工程打包(折腾了好一会..)

        1.1版本的JDoc添加了自动测试的功能(虽然我感觉用不上,还影响整合过程...)

        项目是由Controller->Command->Service->Model.

        Controller只是做个中转,具体的业务写在Command里,那么问题来了 这个文档注释写在Controller上就有点奇怪了.. 

        写在Command上,文档生成的接口访问路径就不对了. 

        举个列子,下图所示.注释参数写在这里,有可能Command里修改了,Controller中给遗漏掉.

blob.png


整合步骤

        1.由于还不在中央库上,所以打包完放到工程中,本地引入

        blob.png

大概是因为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   blob.png    

效果图

blob.png

blob.png        

项目链接

      git地址


评论区

JFinal

2017-04-12 18:17

需要生成 api 的小伙伴们有福了,先收藏、点赞,有小伙伴再问直接给 url

Dreamlu

2017-04-12 18:39

小伙子现在越来越6了啊!

Dreamlu

2017-04-12 18:39

点个赞

小徐同学

2017-04-13 09:17

收藏一波

书语2012

2017-04-14 09:46

谢谢支持JDoc

XiaoFei

2017-04-15 15:15

牛叉

板砖哥

2017-04-18 11:06

赞一个!

小99

2017-04-25 15:24

jdk1.7没法用啊

l745230

2017-04-25 23:33

@小99 偷懒了下,此JDoc整合是基于dubbo整合的基础上,使用到了Jdk1.8。JDK1.8下的dubbo-admin.2.5.4.war需要重新编译。 所以非1.8环境跑不动。

小99

2017-04-30 18:48

@l745230 大部分公司都停留在6和7之间

jf大哥大

2017-05-05 16:13

集成失败,有机会再跑源码

2B的It青年

2017-05-06 01:37

厉害,期待 Jfinal 官方出品的在线 Api 文档,

jiren

2017-07-27 19:49

点赞

jiren

2017-07-27 19:49

阿树

2017-11-16 12:36

jdoc整合jfinal后,controller由于参数不在方法里声明,注释会被idea检查提示没有参数有问题,请问这个有什么好的解决方式吗?

l745230

2017-11-16 19:57

@阿树 放弃JDoc吧,官方都好几个月不进行后续更新了,你现在遇到的还是idea检查提升的问题,后面还有很多坑在等着你,推荐你用Swagger

zhangshiqiang

2017-12-08 11:37

生成的文档 字段无法添加注释。

哈哼哈嘿

2018-01-31 10:47

JDoc是不是只能生成controller层的文档啊?@l745230

l745230

2018-01-31 16:46

哈哼哈嘿

2018-02-01 12:14

@l745230 Swagger 可以吗

l745230

2018-02-01 14:56

@哈哼哈嘿 Swagger 根据注解来生成文档的,理论上是可以这么用,没实践过,你可以试试

哈哼哈嘿

2018-02-01 16:04

@l745230 恩恩,谢谢你