（轉）Swagger2 & Postman工具使用

本文轉載自查看原文 2018-10-24 09:42 4200

（二期）7、swagger2與postman

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

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

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

手寫接口文檔

手寫Api文檔的幾個痛點：

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

接口返回結果不明確

不能直接在線測試接口，通常需要使用工具，比如postman

接口文檔太多，不好管理

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內部錯誤等。

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

......

怎么用RESTful

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

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

3、統一的返回結果

4、返回正確的狀態碼

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

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

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

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

postman簡介

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

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

postman安裝

1、app下載地址