專案中swagger-ui使用歷程

Swagger · 發表 2018-09-18 15:28:37

摘要：現在大家做的java專案基本上都是前後端分離的,後端只提供api介面即可,和前端互動的時候都是用json,然後在這個過程中就會出現一個問題,前後端互動的時候就約定介面的資料格式,然後我們現在的專案前端還是外包給公司外的人做的,給外包提供api介面資料的時候溝通起來非常麻煩,而且文件寫的不完整還...

現在大家做的java專案基本上都是前後端分離的,後端只提供api介面即可,和前端互動的時候都是用json,然後在這個過程中就會出現一個問題,前後端互動的時候就約定介面的資料格式,然後我們現在的專案前端還是外包給公司外的人做的,給外包提供api介面資料的時候溝通起來非常麻煩,而且文件寫的不完整還要被外包說,主要程式員都討厭寫文件,但是不寫介面文件肯定要被前端開發噴死.

這個時候swagger-ui就提現了強大之處了,自動生成文件,不僅可以方便自己寫完介面後除錯,也可以自動生成文件給前端人員除錯,還真挺好用的,但是剛開始用這個,還是遇到了一點點小問題的,下面就說下用的過程中遇到的問題,已經解決辦法.

不過你可能要問了,你這一上來就說遇到的問題,我看了一臉懵逼啊,我現在連swagger怎麼用的,能幹嘛,以及怎麼讓它在專案裡跑起來,你一個都沒說,直接就說問題,你考慮過讀者的感受嗎,哈哈,其實我一開始也想寫篇整合swagger和springboot的部落格,後來發現公司已經有人寫了,https://blog.yayuanzi.com/24317.html,這是對應的連結地址,想看整合的,直接看這篇吧,我這裡就不重複了,直接說遇到的問題吧.

問題1.因為專案是使用前後端分離的,所以session啊什麼的肯定就不能用了,那我要怎麼知道使用者的登入狀態呢,目前普遍的做法是用token,那麼問題就來了,token是放在header裡的,使用swagger呼叫介面的時候沒有傳header的地方,看圖

解決辦法:這裡就需要知道swagger的用法了,網上搜了一下,大概意思就是新增一個全域性的操作,就是所有的介面都增加一個header的引數,程式碼如下.

//新增header引數token
ParameterBuilder tokenPar = new ParameterBuilder();
List<Parameter> pars = new ArrayList<>();
tokenPar.name("token")
.description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
pars.add(tokenPar.build());

return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//為當前包路徑
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.regex("/api/.*"))
.build().globalOperationParameters(pars);

</code>

新增之後再看頁面就會看到一個token令牌得引數,看圖

問題2:swagger返回資料型別都是一個空得大括號,看不到具體得返回型別,這個問題導致了前端開發人員看不到返回資料得格式,或者說看不到具體返回了啥,後來檢查程式碼發現原來是自己的問題,swagger是根據返回資料的型別來生成這個對應的example value的,然後我們的程式碼裡寫的返回型別都是一個ResultVO<T>,在具體的方法返回值裡沒有指明這個泛型在當前具體是什麼型別,導致swagger-ui也不知道是什麼,所有就放了一個空的大括號在那裡,找到問題了那就開始修改程式碼了,其實只要把返回值的型別從ResultVO改成ResultVO<Map<String, List<TradeApiVO>>>就可以了,然後再看效果就是後面那個圖片的效果了.