开发过程中接口文档是一个刚需，开始的时候，我是手写word文档，写着写着发现越到后面越难以进行，于是接触到了swagger这个神器，这里简单记录一下，踩坑过程。使用的框架是Jfinal框架，jfinal社区已经有jfinal-swagger项目了，但是项目并没有完善，使用过程存在一些小问题。
一、到码云上获取jfinal-swagger源码并打包成jar
[email protected]:leeckent/jfinal-swagger.git
下载好进行编译以后，执行jar命令打包：jar cvf jfinal-swagger.jar -C classes/ （classes目录为编译后的文件跟目录）
二、到github上获取swaggerui
https://github.com/swagger-api/swagger-ui.git
三、相关配置，引入swagger到项目中
这里不赘述配置过程了，参考官方提供的readme文件即可，地址
四、爬坑过程
- 如果引入以后直接运行项目，进入api地址以后，会发现一直报空指针异常，异常指向getClassSet方法
Set<Class<?>> classSet = ClassUtil.getClassSet(packageName);一路debug，发现方法最后是获得了set对象的，后来才发现，jar文件中方法居然没有return，然而源码是有的，这个问题不知道是为什么，没研究
- 解析好指定包路径下的Api、ApiOperation等注解以后，发现swaggerui报Can`t read from file /swagger/api的问题，但是查看返回结果发现是返回了json数据的，又是一路懵逼，找了半天，后来想想会不会又是jar包问题，一看，果然，swagger完整的返回json数据格式如下图
而参考例子中只返回了path部分，其实jfinal-swagger已经提供了完整的对象SwaggerDoc，jar包中的controller实例并没有返回完整的SwaggerDoc对象
- 还有一点不完善的，目前只提供了Api、ApiOperation、Params、Param四种注解，Response这个自己写一个注解，并在解析指定包路径下的注解时加上就可以了
其他的都可以根据需要，自己写扩展，这个比起自己写word文档，那简直方便多了，简单可维护，感谢jfinal，贴一张完成后的图
