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

在配置檔案中新增引數

#Swagger開關
SWAGGER.ENABLE = true

@Value()
[email protected]
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 基於以上實現的總結

從實現難度上來說，本套整體實施方案並不複雜，只是需要前後端開發+測試的協同合作即可，前期花一定的時間改造，會對後期的生產力提高起到巨大的幫助，尤其是整個測試周期的縮短，迭代週期的降低起到巨大的幫助。而且整套方案具有可移植性，方便套用到其他任何專案中去。