一、是什麼

　　當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文件將會極大的提高我們的工作效率。傳統意義上的文件都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文件的及時性，這種文件久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文件的方式。

二、為什麼要使用它

　　1、程式碼變更，文件跟著程式碼變、只需要少量的註解Swagger就可以根據程式碼自動的生成API文件，很好的保證了文件的實時性。

　　2、跨語言，Swagger支援40多種語言。

　　3、Swagger UI 呈現出來的是一份可以互動的API文件，我們可以直接在文件頁面嘗試API的呼叫，省去了準備複雜的呼叫引數的過程。

　　4、還可以將文件規範匯入相關的工具裡面（例如：Postman、SoapUI）、這些工具將會為我們自動地建立自動化測試。

三、怎麼用　　

1、在專案pom.xml裡面加入Swagger2相關的依賴

<!--swagger2配置-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.4.0</version>
    </dependency>
    <dependency>
      <groupId>com.github.xiaoymin</groupId>
      <artifactId>swagger-bootstrap-ui</artifactId>
      <version>1.6</version>
    </dependency>

2、新建Swagger2的配置類

package com.zhouhong.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
 * @ClassName: Swagger2
 * @Description:
 * @Author: 周紅
 * @NickName: Tom-shuhu
 * @Date: Created in 2020/12/15
 **/
@Configuration
@EnableSwagger2
public class Swagger2 {
  //  http://localhost:8088/swagger-ui.html 原路徑
  //  http://localhost:8088/doc.html 原路徑
  //配置swagger2核心配置
  @Bean
  public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2) //指定api型別位swagger2
      .apiInfo(apiInfo())            //用於定義api文件彙總資訊
        .select().apis(RequestHandlerSelectors
            .basePackage("com.zhouhong.controller")) //指定生成文件的controller
        .paths(PathSelectors.any())　　　　　　
        .build();
  }
  private ApiInfo apiInfo(){
    return new ApiInfoBuilder()
        .title("Tom-shushu 的專案介面api") //文件標題
        .contact(new Contact("周紅",//作者
            "www.zhouhong.icu",　　
            "[email protected]")) //聯絡人
        .description("Tom-shushu 的專案api介面")//詳細資訊
        .version("1.0.0")//文件版本號
        .termsOfServiceUrl("www.zhouhong.icu")//網站地址
        .build();
  }
}

　　文件配置說明：

　　a.為任何介面生成API文件，這種方式不必在介面方法上加任何註解，方便的同時也會因為沒有新增任何註解所以生成的API文件也沒有註釋，可讀性不高。

 @Bean
  public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        //為任何介面生成API文件
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build();
  }

　　b.為當前配置的包下controller生成API文件

.apis(RequestHandlerSelectors.basePackage("com.troila"))

　　c.為有@Api註解的Controller生成API文件

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))

　　d.為有@ApiOperation註解的方法生成API文件

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

三、常見註解簡介

@Api：修飾整個類，描述Controller的作用
 @ApiOperation：描述一個類的一個方法，或者說一個介面
 @ApiParam：單個引數描述
 @ApiModel：用物件實體來作為入參
 @ApiProperty：用物件接實體收引數時，描述物件的一個欄位
 @ApiResponse：HTTP響應其中1個描述
 @ApiResponses：HTTP響應整體描述
 @ApiIgnore：使用該註解忽略這個API
 @ApiError ：發生錯誤返回的資訊
 @ApiImplicitParam：一個請求引數
 @ApiImplicitParams： 多個請求引數

四、演示（為方便我使用了上面第一種配置）　　

1、使用原路徑訪問

　　2、原路徑除錯

　　3、doc模式訪問

4、doc模式除錯

到此這篇關於SpringBoot整合Swagger2的方法的文章就介紹到這了,更多相關SpringBoot整合Swagger2內容請搜尋我們以前的文章或繼續瀏覽下面的相關文章希望大家以後多多支援我們！