swagger是一個(gè)工具帆离,用于自動(dòng)生成web網(wǎng)站對(duì)外提供的服務(wù)接口文檔,并且以web頁面的形式進(jìn)行展示结澄。
那么我們?yōu)槭裁葱枰@個(gè)工具呢哥谷?這首先需要從web相關(guān)項(xiàng)目的開發(fā)模式說起。
web相關(guān)的項(xiàng)目麻献,可以分為服務(wù)端的開發(fā)和客戶的開發(fā)呼巷。客戶端的形式一般有html頁面赎瑰,android王悍,和其他一些形式。服務(wù)端提供webservice形式的接口餐曼,供客戶端進(jìn)行調(diào)用压储。
當(dāng)服務(wù)端的開發(fā)和客戶端的開發(fā)是由不同的團(tuán)隊(duì)完成的時(shí)候,需要兩個(gè)團(tuán)隊(duì)首先約定好接口的定義源譬。接口的定義一般是由開發(fā)服務(wù)端的團(tuán)隊(duì)來進(jìn)行集惋,把服務(wù)端提供的接口寫成文檔,交給客戶端的開發(fā)人員踩娘,讓他們按照文檔中接口的定義刮刑,來調(diào)用服務(wù)端的服務(wù)程序喉祭。
問題在于,服務(wù)端提供的接口并不能一次完成雷绢,它是在開發(fā)過程中不斷修改的泛烙。那么這就需要服務(wù)端的開發(fā)人員,在每次修改完接口之后翘紊,就要更新一次接口文檔蔽氨,然后把新版的文檔發(fā)給客戶端的開發(fā)人員,讓他們按照新版的文檔進(jìn)行使用帆疟。
如果這個(gè)中間的過程存在滯后鹉究,特別是服務(wù)端和客戶端的開發(fā)團(tuán)隊(duì)在兩個(gè)城市的時(shí)候,那么就特別容易帶來接口不匹配的問題踪宠。
swagger工具自赔,就是為了解決這個(gè)問題而開發(fā)的。它本身是一些jar包柳琢,使用的時(shí)候需要把這些jar包加到服務(wù)端程序的編譯路徑里匿级。服務(wù)接口的開發(fā)跟之前一樣,需要增加的內(nèi)容是染厅,在每個(gè)需要對(duì)外提供服務(wù)的接口的上面加上一些注解痘绎,形如@param等,加上這些注解之后肖粮,swagger工具就能自動(dòng)都把這些接口提取出來孤页,并以網(wǎng)站的形式對(duì)外展現(xiàn)。
除了能夠展現(xiàn)接口的定義之外涩馆,swagger工具還提供了對(duì)接口的單元測(cè)試功能行施,這個(gè)功能能夠幫助客戶端開發(fā)人員對(duì)接口的理解和使用。
使用swagger工具之后魂那,對(duì)于服務(wù)端的開發(fā)人員來講蛾号,就不需要再寫接口文檔了,他們只需要在對(duì)外服務(wù)接口上加上一些注解涯雅,就可以把這些接口展現(xiàn)給客戶端的開發(fā)人員鲜结。接口定義修改了的時(shí)候,只需要同步維護(hù)這些注解活逆,客戶端人員看到的接口就會(huì)同步更新精刷。因?yàn)榫S護(hù)這些注解是在代碼級(jí)的,服務(wù)端的開發(fā)人員在修改代碼的時(shí)候可以同步進(jìn)行修改蔗候,幾乎不耗費(fèi)額外的精力怒允。
而對(duì)于客戶端的開發(fā)人員來講,調(diào)用接口的時(shí)候锈遥,他們不需要再去查看接口文檔了纫事,而是直接查看由swagger工具提供的接口網(wǎng)站勘畔。這里提供的接口定義,比文檔里面的更加準(zhǔn)確丽惶,直接炫七,更新及時(shí)。
總而言之蚊夫,在web網(wǎng)站開發(fā)需要多團(tuán)隊(duì)協(xié)作的時(shí)候使用swagger工具,能夠有效降低不同團(tuán)隊(duì)之間有關(guān)的接口定義的溝通成本懦尝,提高團(tuán)隊(duì)的開發(fā)效率知纷。