01 什麼是Swagger
官方定義:Swagger 是一個規範和完整的框架,用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新。文件的方法,參數和模型緊密集成到服務器端的代碼,允許API來始終保持同步。
簡單點說:就是開發人員用代碼來實現基於實時測試的功能更強大的接口文檔。
02 Swagger的優點與缺點
優點:a).更優美的圖形化接口文檔展示,可以隨時嘗試基於接口的調用來驗證參數。
b).避免後端開發,前端開發,測試之間花費過多的精力在接口參數的溝通上。
c).配合合適的測試工具例如(PostMan/SoupUI等)可以實現自動化測試解決方案。
缺點:a).通過註釋方式實現,對代碼有稍許侵入性。
b).開發人員的不專業可能會導致註釋的請求參數和實際參數不一致,導致接口文檔的不準確
03 基於SpringBoot + Swagger2 的實現
舉例實現基於Web MVC的(由於SpringBoot2實現了WebFlux的非阻塞風格web框架,故以下方案只適用於基於Web MVC風格的項目實現)整個閉環。
Step1:引入Gradle依賴,採用2.7.0版本
Step2:引入Configuration配置。
此處注意:
1).如果採用了MVC異步模式,注意在初始化對應組件時添 加.genericModelSubstitutes(DeferredResult.class)來避免對返回參數的解析不規範的問題。
2),目前行內有許多接口文檔是維護在ShowDoc上的,我們可以在初始化的時候把對應的鏈接加入到我們的Swagger首頁上.termsOfServiceUrl(XXXXX).
Step3:在對應的Controller層添加對應Annotation,並對應標註,主要需要用的參數如下:
//類級別
@Api:用在請求的類上,表示對類的說明
//方法級別註釋
@ApiOperation:用在請求的方法上,說明方法的用途、作用
@ApiImplicitParams:用在請求的方法上,表示一組參數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求參數的各個方面
@ApiResponses:用在請求的方法上,表示一組響應
@ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應信息
//請求/返回對象類級別
@ApiModel:用於響應類上,表示一個返回響應數據的信息
//請求/返回對象屬性級別
@ApiModelProperty:用在屬性上,描述響應類的屬性
截圖詳細解釋如下:
Step 4:所有代碼層面改動已經完成了,編譯啓動項目,然後通過項目URL+特定後綴就可以訪問了,例如項目根目錄是 127.0.0.1:8080/xxx,那麼啓動後Swagger對應鏈接是127.0.0.1:8080/xxx/swagge-ui.html
進入首頁詳情,顯示Configuration中配置各項參數以及抓取的Controller層各個請求入口列表(此處是系統自動,不是手動配置各個Controller)
點擊任意一個描述鏈接,展開當前controller下所有接口
點擊任意一個具體接口,展示所有詳細請求參數,根據之前的配置來說 ,@RequestHeader/@RequestParam/@PathVariable通過@ApiImplicitParam來捕捉,而@RequestBody/@ResponseBody通過@ApiModel來捕捉
此接口文檔界面可以實時嘗試系統的返回結果,通過填寫請求參數,點擊 try it out!
點擊完成以後,系統會實時給出請求具體參數與返回具體參數:
04 在生產中禁用Swagger
在配置文件中添加參數
在配置類中添加配置: 在配置中添加@Profile註解,如果只對sit環境生效,那麼我們就添加參數如下#Swagger開關
SWAGGER.ENABLE = true@Value()
swaggerEnable@Override
addResourceHandlers(ResourceHandlerRegistry registry) {
(swaggerEnable) {
System.out.println(swaggerEnable)registry.addResourceHandler()
.addResourceLocations()registry.addResourceHandler()
.addResourceLocations()}
}
@EnableSwagger2
@Profile()
Swagger2 WebMvcConfigurationSupport {
@Bean
Docket createRestApi() {
Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage())
.paths(PathSelectors.any())
.build()}
ApiInfo apiInfo() {
ApiInfoBuilder()
.title()
.contact(Contact())
.version()
.description()
.build()}
@Override
addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler().addResourceLocations(
)registry.addResourceHandler().addResourceLocations(
)}
}
05 基於PostMan的自動化測試解決方案。
Swagger的首頁有個導出接口提示,如下圖,其鏈接適用於導出所有接口到PostMan/SoupUI中,且一鍵生成(此處是開發和測試的福音!),以下用PostMan演示:
找到API對應後綴
在PostMan中導入操作中輸入對應鏈接
點擊完成,發現所有接口已經自動按照需求自動導入Postman!
以下爲如何在PostMan中完成自定義的一個測試化用例,以用戶登錄並且領卡爲例:
注意:PostMan的Tests標籤頁的語法本質上是Js,如需完成一個測試用例的編寫,需要測試人員掌握一定的前端語法(只需部分簡單語法即可)。如果的確不瞭解,問題也不大,選中Tests的Tab以後,可以看到右邊有很多的snippets,各種現成的Assertion已經準備好了,如返回代碼,是否match特定內容,是否特定包含某部分內容等等。90%的需求都可以滿足。
Step1:創建一個新的Colletion,命名爲項目--測試用例集,然後在Collection中創建子文件夾,每個文件夾代表一個測試用例。從之前導入的接口中運用save as 按鈕把需要的接口導入到對應的測試用例文件夾中,然後選取合適的snippets來完成Assertion,完成單個測試用例的編寫,然後點擊Collection右上角,Run。
Step2:點擊Run按鈕以後,會跳轉到對應的Runner組件,選取對應的測試案例,直接點擊運行。
Step3:運行完畢,系統會給出這個測試案例根據編寫的Tests驗證具體內容的驗證結果(成功個數,失敗個數,返回結果,耗時等等),以及這個測試案例涉及到的所有接口順序驗證的內容結果,我們可以根據預期來判斷是否驗證通過。相比於目前零售端的人力驗證測試案例,功能迴歸可以從天級別的迴歸縮短到分鐘級別的迴歸。
06 基於以上實現的總結
從實現難度上來說,本套整體實施方案並不複雜,只是需要前後端開發+測試的協同合作即可,前期花一定的時間改造,會對後期的生產力提高起到巨大的幫助,尤其是整個測試周期的縮短,迭代週期的降低起到巨大的幫助。而且整套方案具有可移植性,方便套用到其他任何項目中去。