（轉）Swagger2 & Postman工具使用

（二期）七、swagger2與postman

 

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

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

 

隨着互聯網技術的發展，如今的網站架構基本都由原來的後端渲染變成了：前端渲染、前後端分離的形態，而前端和後端的惟一聯繫，變成了API接口；API文檔變成了先後端開發人員聯繫的紐帶，變得愈來愈重要。包括app開發人員和後端直接的交流都是基於api文檔。

手寫接口文檔

手寫Api文檔的幾個痛點：

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

1. 接口返回結果不明確

1. 不能直接在線測試接口，一般須要使用工具，好比postman

1. 接口文檔太多，很差管理

 

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

什麼是swagger2

編寫和維護接口文檔是每一個程序員的職責，根據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：用在屬性上，描述響應類的屬性

springboot整合swagger2

第一步：導入pom

<!-- 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 -->

第二步、SwaggerConfig.java中配置接口文檔基本信息和啓動swagger2支持

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上的。

 

restful風格接口

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 用來刪除資源。好比：

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

POST http://api.qc.com/v1/friends: 添加好友

UPDATE http://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內部錯誤等。

 

一、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 刪除一個小狗狗 

 

二、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  消息體類型報頭 

......

 

怎麼用RESTful

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

二、對於資源的操做類型由HTTP動詞來表示

三、統一的返回結果

四、返回正確的狀態碼

五、容許經過HTTP內容協商，建議格式預約義爲JSON

六、對可選發雜的參數，使用查詢字符串（？）

七、返回有用的錯誤信息(message)

八、非資源請求用動詞，這看起彷佛和1中的說法有矛盾，但這裏指的是非資源，而不是資源

 

postman簡介

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

 

Postman 提供功能強大的 Web API 和 HTTP 請求的調試，它可以發送任何類型的HTTP 請求 (GET, POST, PUT, DELETE...)，而且能附帶任何數量的參數和 Headers。不只如此，它還提供測試數據和環境配置數據的導入導出，付費的 Post Cloud 用戶還可以建立本身的 Team Library 用來團隊協做式的測試，並可以將本身的測試收藏夾和用例數據分享給團隊。

postman安裝

一、app下載地址

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

二、谷歌插件方式

postman經常使用按鈕

• 導入：用於導入你或團隊保存的API請求文件，json格式。

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

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

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

Postman 是有團隊協做的，能夠共享請求參數及數據，但須要註冊且是放在他們的服務器上的，對公司而言，會有安全性的考慮，大多數人很懶，會放棄這種方式。仍是 QQ 發送文件來的方便。

postman使用流程

新建項目

直接點擊左邊上面的添加目錄圖標來新增一個根目錄，至關於新建了一個項目，咱們能夠把一個項目或一個模塊的用例都存放在這個目錄之下，而且在根目錄之下咱們還能夠在創建子目錄來進行功能用例的細分，以下圖所示：

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，即若是你編寫好了用例以後能夠經過點擊「Generate Code」來一鍵生成代碼，而且還有好多語言和類庫能夠選擇，以下圖所示：

批量執行用例

這個功能由單獨的runner來負責的，咱們須要在另外的界面進行操做，具體以下圖所示：

依次點擊上面的按鈕就會出現runer界面，以下直接點擊「Start run」便可，

以下圖所示：