Swagger介紹

1.什么是Swagger

作為后端程式開發，我們多多少少寫過幾個后臺介面專案，不管是撰寫手機端介面，還是目前比較火熱的前后端分離專案，前端與后端都是由不同的工程師進行開發，那么這之間的溝通交流通過介面檔案進行連接，但往往伴隨很多問題，后端程式員認為撰寫介面檔案及維護太花費時間精力，前端的認為介面檔案變動更新不及時，導致程式之間相互呼叫出行問題，那么能簡化介面檔案的撰寫直接自動生成嗎？當然能！如是乎Swagger這種介面檔案在線自動生成工具便孕育而生，

Swagger 是一個規范和完整的框架，用于生成、描述、呼叫和可視化 RESTful 風格的 Web 服務，總體目標是使客戶端和檔案系統作為服務器以同樣的速度來更新，檔案的方法，引數和模型緊密集成到服務器端的代碼，允許API來始終保持同步，Swagger 讓部署管理和使用功能強大的API從未如此簡單，

2.Swagger優點

• 代碼變，檔案變，只需要少量的注解，Swagger 就可以根據代碼自動生成 API 檔案，很好的保證了檔案的時效性，
• 跨語言性，支持 40 多種語言，
• Swagger UI 呈現出來的是一份可互動式的 API 檔案，我們可以直接在檔案頁面嘗試 API 的呼叫，省去了準備復雜的呼叫引數的程序，
• 還可以將檔案規范匯入相關的工具（例如 Postman、SoapUI）, 這些工具將會為我們自動地創建自動化測驗，

SpringBoot中整合Swagger

1.基礎環境構建

首先搭建一個基礎的SpringBoot專案，匯入以下Swagger啟動器

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter<artifactId>
    <version>3.0.0</version>
</dependency>

撰寫一個用于測驗的controller

@RestController
public class HelloController {

    @PostMapping(value = "https://www.cnblogs.com/hello")
    public String hello(){
        return "hello";
    }
}

撰寫Swagger的配置類

@Configuration
@EnableOpenApi
public class SwaggerConfig {
}

運行啟動輸入地址：http://localhost:8080/swagger-ui/index.html

可以看到Swagger介面檔案頁面，說明基本配置環境成功！

注意事項：
Swagger3.0版本的地址是http://localhost:8088/swagger-ui/index.html，2.x版本中訪問的地址的為http://localhost:8088/swagger-ui.html

2.配置Swagger

配置Swagger首先需要構建其Bean實體 Docket物件，在剛剛創建的SwaggerConfig 配置類中創建一個Docket

@Bean
public Docket docket(){
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo());
}

Docket(DocumentationType.OAS_30) ,我們這里選擇的引數是 DocumentationType.OAS_30,這是一個Swagger實體的介面檔案版本，我們這里是3.0，所以選擇用 OAS_30，其他的型別還有如下幾種，分別對應著Swagger歷史版本

 public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
    public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
    public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");

構建Docket需要創建 ApiInfo 實體

private ApiInfo apiInfo(){
    // 作者資訊
    Contact contact = new Contact("TIOXY", "https://www.cnblogs.com/tioxy/", "[email protected]");

    return new ApiInfo(
            "Tioxy的介面檔案",
            "專案描述",
            "1.0",
            "https://www.cnblogs.com/tioxy/",
            contact,
            "Apache 2.0",
            "http://www.apache.org/licenses/LICENSE-2.0",
            new ArrayList());
}

ApiInfo 主要作用是構建我們介面檔案的頁面顯示的基礎資訊，展示如下位置

3.配置掃描介面及開關

構建Docket時通過 select() 方法配置掃描介面，Docket的完整代碼如下：

@Bean
public Docket docket(Environment environment){
    // 設定顯示的Swagger環境
    Profiles dev = Profiles.of("dev");
    // 獲取專案環境
    boolean flag = environment.acceptsProfiles(dev);

    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            // 配置Api檔案分組
            .groupName("TIOXY")
            // enable()是否啟用Swagger，默認是true
            .enable(flag)
            .select()
            // RequestHandlerSelectors,配置要掃描介面的方式
            // basePackage指定要掃描的包
            // any()掃描所有，專案中的所有介面都會被掃描到
            // none()不掃描
            // withClassAnnotation()掃描類上的注解
            // withMethodAnnotation()掃描方法上的注解
            .apis(RequestHandlerSelectors.basePackage("com.tioxy.controller"))
            // paths()過濾某個路徑
            .paths(PathSelectors.any())
            .build();
}

• groupName("TIOXY")：表示此Docket實體的名字，也就是介面檔案頁面右上角選擇的實體名，實際開發中我們是多人開發，對應的就是多個Docket實體
• enable(flag)：enable()是否啟用Swagger，默認是true

我們這里使用的是動態的配置是否啟用Swagger，通過 Environment 來獲取此時運行的專案環境名稱，如果是 dev,則定義一個flag，來動態的設定是否啟用

4.物體類配置

新建一個User物體類

@ApiModel("用戶物體")
public class User {
   @ApiModelProperty("用戶名")
   public String username;
   @ApiModelProperty("密碼")
   public String password;
}

只要這個物體在請求介面的回傳值上（即使是泛型），都能映射到物體項中：

@RequestMapping("/getUser")
public User getUser(){
   return new User();
}

5.常用注解

我們也可以在介面上添加注釋說明，方便我們在介面檔案中解釋說明介面的資訊，例如介面的作用、引數說明等，方便呼叫者使用

文章參考
狂神說Java系列之SpringBoot整合Swagger學習筆記

標籤：Java

上一篇：Java連載133-ResultSet介面的其他方法

下一篇：簡化RESTful開發，Spring Data REST讓你少掉發