SpringBoot學習之整合Swagger

TIOXY發表於2020-08-08
Spring BootSwagger

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 = "/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/", "1369773052@qq.com");

    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.常用註解

我們也可以在介面上新增註釋說明，方便我們在介面文件中解釋說明介面的資訊，例如介面的作用、引數說明等，方便呼叫者使用

Swagger註解 簡單說明
@Api(tags = "xxx模組說明") 作用在模組類上
@ApiOperation("xxx介面說明") 作用在介面方法上
@ApiModel("xxxPOJO說明") 作用在模型類上：如VO、BO
@ApiModelProperty(value = "xxx屬性說明",hidden = true) 作用在類方法和屬性上，hidden設定為true可以隱藏該屬性
@ApiParam("xxx引數說明") 作用在引數、方法和欄位上，類似@ApiModelProperty

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

相關文章