背景

    之前分享过一次JFinal整合JDoc1.1， 整合后一直在忙于开发，没去系统的整理文档，只是陆陆续续的关注着JDoc的群,看看其他小伙伴遇到的问题跟反馈。 

    http://www.jfinal.com/share/262

    昨天有空了，又掏出JDoc写了一波文档，发现了很多BUG，加上今天看到一篇集成Swagger的文章，打算抛弃JDoc了。

    http://www.jfinal.com/share/347

分享

     1.潜水观察，大伙遇到的最多问题就是tools，各种配置系统环境,各种折腾。

直接从本地引入，是最方便快捷的了，传到git上，小伙伴们把工程下载下来，也不用在去折腾环境配置，直接用！特别是env这个环境变量，配置起来要命！

2.文档生成时，各种红字报错

    很多人都把JDoc的自动测试给配置上了,这会引发很多潜在BUG，比如不管你的JFinal路由是怎么配置的（“/AaaBbb”,AaaBbbController.class）.目前JDoc都处理成/aaabbb，导致测试接口不通过,因而文档无法生成。

#use.analysis=true
#analysis.prefix.url=

以上这2个地方注意下，基本上我周围的小伙伴就没遇到其他问题了

BUG

    除开JDoc生成文档时，api路径全是小写外，还发现了一些BUG

    1.测试功能，参数带空格,idea格式化后内容对齐，此功能就用不了了

    2.接上图，idea下@param注释找不到action中队友的参数,idea报错提示，虽然不影响，但是轻微处女座患者看着别扭。 据说JFinal3.2-JDK1.8版本可以参数注入了,但是运维小伙伴就是不升级服务器到1.8 我也是很无奈啊。

    3.不同环境下,api访问路径，一般来说既然提供了接口测试功能，那么就需要对开发环境/测试环境/正式环境的接口进行调用测试。 目前JDoc未提供此功能，跟作者沟通后的解决方案，是修改配置文件，分别生成开发环境.html、测试环境html、正式环境html3份文档。

    那么开工，在生成文档的过程中，发现同一个main方法执行中，只会生成出第一个启动的JFinalApiDocConfig,后面的JFinalApiDocConfig被忽略。

    虽然这个问题写3个Main方法，分别执行也能解决。

最后

    附上我的JDoc配置,其实就是官方的配置，去掉了自动测试

#指定java文件路径
java.source=src/main/java
#指定需要生成文档的包路径
package.name=com.longxing.admin
#指定采用的框架类型,目前支持jfinal,springmvc两种框架
parser.name=jfinal
#指定文档输出路径
out.path=src/main/webapp/api-cms.html
#指定模版生成器，目前仅支持html
parser.formater=html
#use.analysis=true
#analysis.prefix.url=http://localhost:9080/
#接口前缀
api.prefix=http://localhost:9080/admin/api/v1 

    还有我昨天花了半小时写好的文档。

准备抛弃JDoc的主要原因

    原先用JDoc本意就是想找Swagger的替代品，现在能用上Swagger了，就换了。相比之下Swagger更加成熟点。