SpringBoot學習之整合Swagger

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/", "[e-mail]");

    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學習筆記