走進Java接口測試之接口管理工具Swagger2

前言

現在都奉行前後端分離開發和微服務大行其道，前後端技術在各自道路上越走越遠。
前後端唯一聯繫變成了API接口，API文檔變成了前後端開發人員&測試人員聯繫的紐帶。所以一款強大的Restful API文檔就變得至關重要了。而目前在後端領域，基本上是Swagger的天下了。

Swagger2綜述

Swagger是一款Restful 接口的文檔在線自動生成、功能測試框架。一個規範和完整的框架，用於生成、描述、調用和可視化Restful 風格的Web服務，加上Swagger-UI，可以有很好的呈現。

Swagger是一組開源項目，其中主要項目如下：

• Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。
• Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行集成。
• Swagger-js: 用於JavaScript的Swagger實現。
• Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。
• Swagger-UI：一個無依賴的HTML、JS和CSS集合，可以爲Swagger兼容API動態生成優雅文檔。
• Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。

Swagger-UI 是什麼？

Swagger-UI 是一款Restful接口的文檔在線自動生成+功能測試功能軟件。
Swagger-UI 的官方地址：http://swagger.io/
Github上的項目地址：https://github.com/swagger-api/swagger-ui
官方提供的demo地址：http://petstore.swagger.io/

爲什麼API接口文檔用Swagger-UI ？

現在多數的項目開發中，網站和移動端都需要進行數據交互和對接，這少不了使用Restful編寫API接口這種場景。 特別是不同開發&測試團隊協作時，就更需要以規範和文檔作爲標準和協作基礎。良好的文檔可以減少溝通成本，達到事半功倍的效果。
有時對一些API說明的理解比較模糊，總想着能直接驗證一下自己的理解就好了，而不是需要去項目寫測試代碼來驗證自己的想法。即API文檔應具備直接執行能力，這種能力類似word,wiki等是無法提供。Swagger-UI 就是這樣一種利器，基於Html+Javascript實現，傾向於在線文檔和測試，使用和集成十分簡單，能容易地生成不同模塊下的API列表， 每個API接口描述和參數、請求方法都能定製並直接測試得到直觀的響應數據。

Swagger-UI 怎麼用？

目前官方提供的Swagger-UI 的使用方式主要有2種：

• 與不同的服務端代碼集成，在服務端代碼中嵌入SwaggerUI文檔生成代碼，部署時自動生成。
• 手動編輯對應的Json文檔，該Json文檔有其特定格式，相對比較複雜，手動編寫難度比較大，可通過官方提供的在線編輯來實現。

與SpringBoot集成

pom依賴包

  <!--引入swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

編寫配置文件SwaggerConfig

/**
 * 主要是添加註解@EnableSwagger2和定義Docket的bean類。
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    //是否開啓swagger，正式環境一般是需要關閉的，可根據Springboot的多環境配置進行設置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否開啓
                .enable(swaggerEnabled).select()
                // 掃描的路徑包
                .apis(RequestHandlerSelectors.basePackage("com.techstar"))
                // 指定路徑處理PathSelectors.any()代表所有的路徑
                .paths(PathSelectors.any()).build().pathMapping("/");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用示例")
                .description("7DGroup | zuozewei")
                // 作者信息
                .contact(new Contact("zuozewei", "https://blog.csdn.net/zuozewei", "[email protected]"))
                .version("1.0.0")
                .build();
    }
}

添加文檔內容(一般上是在Controller，請求參數上進行註解)
添加MyGetMethod類，這裏演示兩個Get請求

@RestController
@RequestMapping("/")
@Api(tags = "API文檔",value = "/",description = "這是我全部的Get方法")
public class MyGetMethod {

    @GetMapping(value = "/getCookies")
    @ApiOperation(value = "通過這個方法可以獲取到Cookies",httpMethod = "GET")
    public String getCookies(HttpServletResponse response){
        //HttpServerletRequest 裝請求信息的類
        //HttpServerletResponse  裝響應信息的類
        Cookie cookie = new Cookie("login","true");
        response.addCookie(cookie);
        return "恭喜zuozewei獲得cookies信息成功";
    }

    /**
     * 要求客戶端攜帶cookies訪問
     * 這是一個需要攜帶cookies信息才能訪問的get請求
     */
    @GetMapping(value = "/get/with/cookies")
    @ApiOperation(value = "通過這個方法可以獲取到Cookies",httpMethod = "GET")
    public String getWithCookies(HttpServletRequest request){
        Cookie[] cookies = request.getCookies();
        if (Objects.isNull(cookies)){
            return "必須攜帶cookies信息來";
        }
        for (Cookie cookie:cookies){
            if (cookie.getName().equals("login") && cookie.getValue().equals("true")){
                return "這是一個需要帶着cookies信息才能訪問的get請求";
            }
        }

        return "必須攜帶cookies信息來";
    }
}

配置全局配置文件application.properties

# 默認的端口號
server.port=8888

# 開啓swagger
swagger.enabled=true

啓動項目

Swagger-UI 訪問與使用

API首頁路徑：http://127.0.0.1:8888/swagger-ui.html

點擊需要訪問的API列表，查看接口詳情，點擊try it out按鈕測試
執行測試

服務端返回結果

Swagger使用的註解及其說明：
@Api：用在類上，說明該類的作用。
@ApiOperation：註解來給API增加方法說明。
@ApiImplicitParams : 用在方法上包含一組參數說明。
@ApiImplicitParam：用來註解來給方法入參增加說明。
@ApiResponses：用於表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息

• l code：數字，例如400
• l message：信息，例如"請求參數沒填好"
• l response：拋出異常的類

@ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam註解進行描述的時候）
@ApiModelProperty：描述一個model的屬性

對於其他註解，大家可自動谷歌，畢竟常用的就這幾個了。有了swagger之後，原本一些接口請求需要Postman這樣的調試工具來進行發起，而現在直接在頁面上就可以進行調試了，是不是很爽？
對於測試人員，有了這份API文檔也是一目瞭然，不需要和後端多少溝通成本，按着API說明進行接口測試腳本開發即可。

小結

本文主要是對Swagger的簡單使用和Springboot集成進行了說明，詳細的用法，可自行搜索相關資料下，這裏就不闡述了。因爲對於百分之八十之上的文檔要求基本能滿足了。最後，一定要在生產環境關閉Swagger,基於安全因素。