Swagger筆記

現在市面上大多數公司都摒棄了傳統 jsp 開發，采用前后端分離式的開發規則，前端使用 Vue，Angular，React 等等完成頁面，后端省掉了視圖跳轉的程序，直接書寫介面回傳 json 資料供前端呼叫即可

這樣一來就誕生了一個新的問題，后端程式員需要寫一個介面檔案來告訴前端開發人員都有那些介面，每個介面都是干什么的，需要那些引數等等，

書寫介面檔案是一件費時費力的活，而 Swagger 可以根據程式代碼自動生成在線介面檔案，Swagger 是介面檔案生成工具

整合Swagger

匯入依賴

想要整合使用 Swagger 生成介面檔案，首先我們需要參考 Swagger 的 maven 依賴：

<!-- 位于io.springfox下的依賴 -->
<dependency>     <!-- Swagger的注解依賴包 -->
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>     <!-- Swagger介面檔案頁面包 -->
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

啟用Swagger

在參考 Swagger 的依賴后，我們還需要通過注解開啟 Swagge 才可以實作介面檔案

新建一個配置類，通過 @EnableSwagger2 注解啟用 Swagger：

@Configuration
@EnableSwagger2   // 開啟Swagger
public class SwaggerConfig { }

了解介面檔案

Swagger 介面檔案主要有四部分組成：

【分組資訊】，【分組描述資訊】，【介面描述資訊】，【物體類資訊】

我們目前僅僅是引入了 Swagger 的依賴，開啟 Swagger 功能之后如果沒有配置的話，默認會使用 swagger 初始化的配置

初始化分組

我們想要使用自定義的分組資訊，要在配置類提供一個 Docket 實體到 IOC 容器中，通過 Docket 實體設定分組名稱，Swagger 會根據實體進行自定義設定，

創建一個分組

// 還是之前的配置類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("張涵哲的分組");
    }
}

上面使用 Swagger2 默認規則創建了一個 Docket 物件，定義分組名稱為 張涵哲的分組，效果如圖所示：

多分組配置

如果想要創建多個分組，那么就在 IOC 容器中多提供幾個 docket 實體：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("張涵哲的分組");
    }
    @Bean
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("***的分組");
    }
}

配置分組詳情

配置分組描述

我們已經可以創建多個分組了，但是我們可以發現，每個分組中都有一段描述資訊，我們可以在每個分組下顯示不同的描述資訊，需要呼叫 Docket 的 apiInfo() 函式傳入自定義的配置，

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("張涵哲的分組")
                .apiInfo(apiInfo());
    }
	// 創建一個函式用來回傳 ApiInfo 實體
    // 這里我只顯示了部分資訊，填寫null的都是不顯示的，如果想要全部顯示可以填寫所有的資訊
    public ApiInfo apiInfo() {
        Contact contact = new Contact("張涵哲", "http://blog.hanzhe.club", null);
        return new ApiInfo(
                "基于Swagger2.0練習",
                "基于程式中所有的介面提供幫助檔案",
                "1.0.0",
                null,
                contact,
                null,
                null,
                new ArrayList());
    }
}

我們為 張涵哲的分組 配置了一段描述資訊，接下來看看效果：

可以看到分組的描述資訊已經顯示出來了，

配置掃描范圍

當我們多個人同時開發一個程式時，就會使用多個分組，每個人對應這一個分組，其中每個分組都有自己的介面檔案，這里需要配置分組介面顯示

例：張涵哲負責開發用戶相關的介面 包位置：club.hanzhe.controller.user.UserController.java

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("張涵哲的分組")
        .apiInfo(apiInfo())
        // select開始，build結束，apis用來過濾
        .select()
        .apis(RequestHandlerSelectors.basePackage("club.hanzhe.controller.user"))
        .build();
}

這樣一來該分組下就只會顯示固定的介面資訊了，除開通過包掃描的方法之外還有其他的方法進行篩選：

RequestHandlerSelectors 類中其他的靜態函式：

還可以通過路徑進行過濾：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("張涵哲的分組")
        .apiInfo(apiInfo())
        // select開始，build結束，paths用來過濾
        .select()
        .paths(PathSelectors.ant("/user/**"))
        .build();
}

PathSelectors 類中其他的靜態函式：

介面資訊配置

簡單介面顯示

上面的圖片是掃描到介面后默認生成的介面檔案，Swagger 是以 Controller 為單位，對介面進行分組管理的，這個分組的元素在 Swagger 中稱為 Tag，我們可以通過注解來修改一下介面檔案，讓他更人性化：

例如下面我們編輯一下當前的 UserController：

@Api(tags = "User介面檔案")
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/")
    @ApiOperation("查詢所有user")
    public R getList(){ ... }

    @PostMapping("/")
    @ApiOperation(valuehttps://www.cnblogs.com/hanzhe/p/= "添加新的user資訊", notes = "傳入用戶資訊進行封裝user進行添加")
    public R addUser(@RequestBody UserBean user){ ... }
    
    @PutMapping("/{id}")
    @ApiOperation(valuehttps://www.cnblogs.com/hanzhe/p/= "通過ID更新user資訊", notes = "路徑傳入ID，json傳輸修改資訊")
    public R updateUser(@PathVariable("id")Long id, @RequestBody UserBean user){
    	...
    }
    
    @DeleteMapping("/{id}")
    @ApiOperation(valuehttps://www.cnblogs.com/hanzhe/p/= "通過ID洗掉user資訊", notes = "路徑傳入ID進行洗掉")
    public R deleteUser(@ApiParam("洗掉的目標ID")@PathVariable("id") Long id){
        ...
    }
    
}

效果如下圖所示：

跨組顯示介面

之前有說過，Swagger 默認是按照每個 Controller 為一個分組顯示介面的，那么如果我們其中一個 Controlle 執行時需要另個 Controller 的某個介面配合，這時我們當前分組就要支持顯示其他分組資訊，

**1. **員工的分組介面除了本身的增刪改查之外還要查詢攜帶查詢所有部門資訊：

@Api(tags = "部門介面")
@RestController
@RequestMapping("/dept")
public class DeptController {

    @GetMapping("/")    // tags 是一個陣列，可以制定多個分組同時顯示
    @ApiOperation( valuehttps://www.cnblogs.com/hanzhe/p/= "查詢所有部門", tags = {"部門介面", "員工介面"})
    public void getList(){ }
    
    // .... 省略其他介面

}

如下圖所示：

通過已有的介面新建一個分組

除了介面跨分組顯示之外，還可以在多個不同的介面中指向同一個不存在的分組，Swagger 會新建一個分組來展示這些介面資訊，

@Api(tags = "員工介面")
@RestController
@RequestMapping("/user")
public class UserController {
    @DeleteMapping("/{id}")
    @ApiOperation(valuehttps://www.cnblogs.com/hanzhe/p/= "通過ID洗掉user資訊", 
                  notes = "路徑傳入ID進行洗掉", tags = "洗掉操作相關介面")
    public R deleteUser(@ApiParam("洗掉的目標ID")@PathVariable("id") Long id){
        ...
    }
}

@Api(tags = "部門介面")
@RestController
@RequestMapping("/dept")
public class DeptController {
    @DeleteMapping("/{id}")
    @ApiOperation(valuehttps://www.cnblogs.com/hanzhe/p/= "通過ID洗掉部門", tags = "洗掉操作相關介面")
    public void deleteUser(@ApiParam("洗掉的目標ID")@PathVariable("id") Long id){ }
}

物體類資訊配置

我們在開始的時候就 Swagger 介面檔案由 分組，分組描述資訊，介面資訊，物體類資訊 四部分組成，前三種我們已經使用過了，接下來我們就要學習使用配置類資訊

當我們需要完成類似添加操作的時候，如果需要的引數過多，使用 @ApiParam 注解就會太過臃腫，直接封裝為物體類又要解釋每個欄位都是干什么的，是什么型別，介面顯示也過于繁瑣，所以我們可以將物體類直接顯示在檔案中，當時用到該物體類時在底部翻找屬性對應引數即可，一個物體類可以對應 N 多個介面，一勞永逸

物體類的配置

配置物體類十分的簡單，只需要使用兩個注解就可以完成基本操作：

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("員工物體類")
public class UserBean {

    @ApiModelProperty("員工ID，用來識別員工的唯一表示，不可重復，")
    private Long id;
    @ApiModelProperty("員工姓名")
    private String name;
    @ApiModelProperty("員工年齡")
    private Integer age;

}

效果如圖所示：

標籤：Java

上一篇：【2021跨年】最浪漫的煙花程式，送給新的一年的自己！（原始碼）

下一篇：Java語言發展史和平臺概述