文章目錄

• 前言
• Swagger2綜述
• Swagger-UI 是什麼？
• 為什麼API介面文件用Swagger-UI ？
• Swagger-UI 怎麼用？
• 與SpringBoot整合
• Swagger-UI 訪問與使用
• 小結

前言

現在都奉行前後端分離開發和微服務大行其道，前後端技術在各自道路上越走越遠。
前後端唯一聯絡變成了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 的官方地址：

為什麼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,基於安全因素。