【課程七】swagge...tman.xmind0.3MB

【課程七預習】sw...tman.xmind31.3KB

隨著網際網路技術的發展，現在的網站架構基本都由原來的後端渲染變成了：前端渲染、先後端分離的形態，而前端和後端的唯一聯絡，變成了API介面；API文件變成了前後端開發人員聯絡的紐帶，變得越來越重要。包括app開發人員和後端直接的交流都是基於api文件。

手寫Api文件的幾個痛點：

1. 文件需要更新的時候，需要再次傳送一份給前端，也就是文件更新交流不及時。

1. 介面返回結果不明確

1. 不能直接線上測試介面，通常需要使用工具，比如postman

1. 介面文件太多，不好管理

• swagger就是一款讓你更好的書寫API文件的框架。

編寫和維護介面文件是每個程式設計師的職責，根據Swagger2可以快速幫助我們編寫最新的API介面文件，再也不用擔心開會前仍忙於整理各種資料了，間接提升了團隊開發的溝通效率。

swagger通過註解表明該介面會生成文件，包括介面名、請求方法、引數、返回資訊的等等。

• @Api：修飾整個類，描述Controller的作用

• @ApiOperation：描述一個類的一個方法，或者說一個介面

• @ApiParam：單個引數描述

• @ApiModel：用物件來接收引數

• @ApiProperty：用物件接收引數時，描述物件的一個欄位

• @ApiResponse：HTTP響應其中1個描述

• @ApiResponses：HTTP響應整體描述

• @ApiIgnore：使用該註解忽略這個API

• @ApiError ：發生錯誤返回的資訊

• @ApiImplicitParam：一個請求引數

• @ApiImplicitParams：多個請求引數

@Api：用在請求的類上，表示對類的說明

    tags="說明該類的作用，可以在UI介面上看到的註解"

    value="該引數沒什麼意義，在UI介面上也看到，所以不需要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、作用

    value="說明方法的用途、作用"
 

    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組引數說明

    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面

        name：引數名

        value：引數的漢字說明、解釋

        required：引數是否必須傳

        paramType：引數放在哪個地方

            · header --> 請求引數的獲取：@RequestHeader

            · query --> 請求引數的獲取：@RequestParam

            · path（用於restful介面）--> 請求引數的獲取：@PathVariable

            · body（不常用）

            · form（不常用）    

        dataType：引數型別，預設String，其它值dataType="Integer"       

        defaultValue：引數的預設值

@ApiResponses：用在請求的方法上，表示一組響應

    @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊

        code：數字，例如400

        message：資訊，例如"請求引數沒填好"

        response：丟擲異常的類

@ApiModel：用於響應類上，表示一個返回響應資料的資訊

            （這種一般用在post建立的時候，使用@RequestBody這樣的場景，

            請求引數無法使用@ApiImplicitParam註解進行描述的時候）

    @ApiModelProperty：用在屬性上，描述響應類的屬性

<!-- Swagger -->

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger-ui</artifactId>

    <version>2.8.0</version>

</dependency>

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-swagger2</artifactId>

    <version>2.8.0</version>

</dependency>

<!-- END Swagger -->

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration

@EnableSwagger2

public class SwaggerConfig {

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .select()

            .apis(RequestHandlerSelectors.basePackage("hello"))

            .paths(PathSelectors.any())

            .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

            .title("Spring Boot中使用Swagger2構建RESTful APIs")

            .description("歡迎來到java思維導圖社群學習")

            .termsOfServiceUrl("http://www.java-mindmap.com/")

            .version("1.0")

            .build();

    }

}

@RequestBody

該註解常用來處理Content-Type: 不是application/x-www-form-urlencoded編碼的內容，例如application/json, application/xml等；它是通過使用HandlerAdapter 配置的HttpMessageConverters來解析post data body，然後繫結到相應的bean上的。

URL定位資源，用HTTP動詞（GET,POST,DELETE,DETC）描述操作。

識別(identify)、 表示(represent) 、互動(interact with)。

• 看Url就知道要什麼

• 看http method就知道幹什麼

• 看http status code就知道結果如何

1. REST描述的是在網路中client和server的一種互動形式；REST本身不實用，實用的是如何設計 RESTful API（REST風格的網路介面）；

2. Server提供的RESTful API中，URL中只使用名詞來指定資源，原則上不使用動詞。“資源”是REST架構或者說整個網路處理的核心。比如：

http://api.qc.com/v1/newsfeed: 獲取某人的新鮮;

http://api.qc.com/v1/friends: 獲取某人的好友列表;

http://api.qc.com/v1/profile: 獲取某人的詳細資訊;

3. 用HTTP協議裡的動詞來實現資源的新增，修改，刪除等操作。即通過HTTP動詞來實現資源的狀態扭轉：

GET 用來獲取資源，

POST 用來新建資源（也可以用於更新資源），

PUT 用來更新資源，

DELETE 用來刪除資源。比如：

DELETEhttp://api.qc.com/v1/friends: 刪除某人的好友 （在http parameter指定好友id）

POSThttp://api.qc.com/v1/friends: 新增好友

UPDATEhttp://api.qc.com/v1/profile: 更新個人資料

4. Server和Client之間傳遞某資源的一個表現形式，比如用JSON，XML傳輸文字，或者用JPG，WebP傳輸圖片等。當然還可以壓縮HTTP傳輸時的資料（on-wire data compression）。

5. 用 HTTP Status Code傳遞Server的狀態資訊。比如最常用的 200 表示成功，500 表示Server內部錯誤等。

1、REST 是面向資源的，這個概念非常重要，而資源是通過 URI 進行暴露。

比如：左邊是錯誤的設計，而右邊是正確的

GET /rest/api/getDogs --> GET /rest/api/dogs 獲取所有小狗狗 

GET /rest/api/addDogs --> POST /rest/api/dogs 新增一個小狗狗 

GET /rest/api/editDogs/:dog_id --> PUT /rest/api/dogs/:dog_id 修改一個小狗狗 

GET /rest/api/deleteDogs/:dog_id --> DELETE /rest/api/dogs/:dog_id 刪除一個小狗狗 

2、REST很好地利用了HTTP本身就有的一些特徵，如HTTP動詞、HTTP狀態碼、HTTP報頭等等。

• HTTP動詞

GET     獲取一個資源 

POST    新增一個資源 

PUT     修改一個資源 

DELETE  刪除一個資源 

• HTTP狀態碼

200 OK 

400 Bad Request 

500 Internal Server Error

• HTTP報頭

Authorization 認證報頭 

Cache-Control 快取報頭 

Cnotent-Type  訊息體型別報頭 

......

1、每個資源使用2個URL，網址中只能有名詞

2、對於資源的操作型別由HTTP動詞來表示

3、統一的返回結果

4、返回正確的狀態碼

5、允許通過HTTP內容協商，建議格式預定義為JSON

6、對可選發雜的引數，使用查詢字串（？）

7、返回有用的錯誤資訊(message)

8、非資源請求用動詞，這看起似乎和1中的說法有矛盾，但這裡指的是非資源，而不是資源

Postman 是一個很強大的 API除錯、Http請求的工具，當你還準備拿著記事本傻傻的去寫 Form 表單的時候，你來試試 Postman。

Postman 提供功能強大的 Web API 和 HTTP 請求的除錯，它能夠傳送任何型別的HTTP 請求 (GET, POST, PUT, DELETE...)，並且能附帶任何數量的引數和 Headers。不僅如此，它還提供測試資料和環境配置資料的匯入匯出，付費的 Post Cloud 使用者還能夠建立自己的 Team Library 用來團隊協作式的測試，並能夠將自己的測試收藏夾和用例資料分享給團隊。

1、app下載地址

• https://app.getpostman.com/app/download/win64

2、谷歌外掛方式

• 匯入：用於匯入你或團隊儲存的API請求檔案，json格式。

• 新建資料夾：用於API請求分門別類，便於管理。

• 儲存請求：儲存你的API請求，返回值也能儲存下來。

• 下載：下載你測試通過的API請求，團隊共享，匯入。json格式，可手動編輯的。

Postman 是有團隊協作的，可以共享請求引數及資料，但需要註冊且是放在他們的伺服器上的，對公司而言，會有安全性的考慮，大多數人很懶，會放棄這種方式。還是 QQ 傳送檔案來的方便。

新建專案

直接點選左邊上面的新增目錄圖示來新增一個根目錄，相當於新建了一個專案，我們可以把一個專案或一個模組的用例都存放在這個目錄之下，並且在根目錄之下我們還可以在建立子目錄來進行功能用例的細分，如下圖所示：

2

新建用例

點選右側區域的+號，新增一個空用例的模板，也可以通過複製一個已有用例來達到新建一個用例的目的，2種方法，如下圖所示：

3

新增請求資訊

新建的用例請求為空，需要新增請求資訊，如下圖所示：

1）選擇一個請求方法，如：get或post

2）填寫請求的url，如：http://www.baidu.com

3）如果是get則請求引數直接寫在url後，用？連線

4）如果是post則請求新增在body中

5）點選“send”傳送請求

6）檢視請求響應內容

4

Post請求引數示例：

post請求的主要特點是把請求資料放在body中，而非url後，如下圖所示：

上面的樣例是post方式傳輸普通引數，如果我們需要傳送帶檔案的請求時，就要改下請求格式了，具體如下圖所示：

注意上面標紅框的部分都必須要對應上，如下圖所示：

新增請求頭資訊

有時候請求還需要新增特定的頭資訊，postman同樣可以完美的支援，直接點選Headers標籤就可以進行請求頭的資訊設定，如下圖所示：

預處理和結果檢查

預處理主要是針對一些環境變數的設定，相當於資料初始化，如下圖所示：

響應處理就是對響應結果進行分析和驗證，比如檢查code是不是200，內容是不是等於具體某個值，是否包含特定的值等等，如下圖所示：

因為預處理和結果檢查都是使用js作為指令碼語言，所以還可以進行任意的js可以實現的場景來輔助測試.

全域性變數與環境變數

全域性變數我們可以自己在預處理和結果處理2個指令碼環境裡進行賦值

在具體的測試資料裡我們就可以直接使用，具體的使用方法是為：{{variable_key}}；比如你在指令碼中可以設定全域性變數：

postman.setGlobalVariable("username","tester");

那麼在用例資料項裡面我就可以這樣使用，{{username}}，用來代表具體的tester值，具體如下圖所示：

而環境變數的設定與使用與全域性變數基本一樣，只是環境變數我們還有另外一個入口可以進行設定，那就是環境配置管理中，

我們可以預先建立若干和與環境相關的一套變數，根據實際的測試需求在執行前選擇對應的環境變數模板，

這樣可以快速切換測試伺服器與線上伺服器之前的環境差異。

比如：配置2套環境變數模板，一套url是測試環境，另一套為線上環境，根據測試物件不同我們選擇不同的環境變數模板就行了，而不再需要修改測試資料中的url了，如下圖所示：

上面我們就把請求的host提取出來，然後在不同環境變數模板裡使用不同的url值，後面我們就可以通過選擇不同的環境變數模板來進行對應的請求測試。

匯出用例為程式碼

postman還有一個很讚的地方就是匯出用例為CODE，即如果你編寫好了用例之後可以通過點選“GenerateCode”來一鍵生成程式碼，並且還有好多語言和類庫可以選擇，如下圖所示：

批量執行用例

這個功能由單獨的runner來負責的，我們需要在另外的介面進行操作，具體如下圖所示：

依次點選上面的按鈕就會出現runer介面，如下直接點選“Start run”即可，

如下圖所示：