開發過程中介面文件是一個剛需，開始的時候，我是手寫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

三、相關配置，引入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，貼一張完成後的圖