07SpringBoot整合Swagger

Swagger簡介：

前後端分離問題的出現造就了Swagger的出現，問題就是：前後端的整合，前端或者後端無法做到及時協商，儘早解決，最終會導致問題集中的爆發。Swagger的出現實時跟蹤了最新的API,降低整合風險。

Swagger是個優秀的工具，現在國內已經有很多的中小型網際網路公司都在使用它，相較於傳統的要先出Word介面文件再測試的方式，顯然這樣也更符合現在的快速迭代開發行情。當然了，提醒下大家在正式環境要記得關閉Swagger，一來出於安全考慮二來也可以節省執行時記憶體。

優點

1. 號稱世界上最流行的API框架
2. Restful API文件自動生成器==>API文件與API定義同步更新
3. 直接執行，線上測試API
4. 支援多種語言，如：JAVA PHP等
5. 官網：https://swagger.io/

SpringBoot整合Swagger

要求：jdk1.8+否則swagger2無法執行。
步驟：
1.新增Maven依賴

  <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>com.github.onsoul</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.2</version>
        </dependency>

2.要使用Swagger，我們需要編寫一個配置類，SwaggerConfig來配置Swagger

@Configuration//配置類
@EnableSwagger2//開啟Swaagger2的自動配置
public class SwaggerConfig{
}

訪問：http://localhost:8080/swagger-ui.html,可以看到以下頁面

配置Swagger

1.Swagger的例項Bean是Docket,所以通過配置Docket例項來配置Swagger

@Bean//配置docket以配置Swagger具體引數
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2);
}

2.可以通過apilnfo()屬性配置文件資訊

//配置文件資訊
 private ApiInfo apiInfo(){
        Contact contact=new Contact("王昌軍",
                "https://mp.csdn.net/console/home?spm=1010.2135.3001.4503",
                "1518461697@qq.com");

        return new ApiInfo("王昌軍的Swagger的文件",//標題
                "要什麼頭髮啊",//描述
                "2.0",//版本
                "https://mp.csdn.net/console/home?spm=1010.2135.3001.4503",//組織連線
                contact,//上面的聯絡人資訊
                "Apache 2.0",//許可
                "http://www.apache.org/licenses/LICENSE-2.0",//許可連結
                new ArrayList());//擴充套件
    }

3.將Docket例項關聯上apilInfo()

public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2).apilnfo(apilnfo);
}

重啟專案。訪問頁面：

配置掃描介面

1.構建Docket時通過select()方法配置要掃描的介面

public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apilnfo(apilnfo)
.select()//通過select方法去配置掃描的介面，RequestHandlerSelectors配置如何掃描介面
.apis(RequestHandlerSelectors.basePackage("com.wang.controller"))
.build();
}

重啟專案測試後，根據配置掃描介面的路徑，可以看到一個類：
除了通過包路徑配置掃描介面，可以通過配置其他事方式掃描介面，這裡列舉了所有的配置方式：

1. any() //掃默所有，專案中的所有介面都會被掃描到
2. none()//不掃描介面
3. withMethodAnnotation(final Class<? extends Annotation> annotation)//通過方法上的註解掃描，例如：withMethodAnnotation(GetMapping.class)只掃描到get請求
4. withClassAnnotation(final Class<? extends Annotation> annotation)//通過類上的註解掃描，例如：withClassAnnotation(Controller.class)只掃描有controller註解類中的介面
5. basePackage(final String basePackage)//根據包的路徑掃描介面

除此以外，我們還可以配置介面掃描的過濾，接在.apis()下：

 .apis(RequestHandlerSelectors.basePackage("com.wang.controller"))//配置要掃描的包
              .paths(PathSelectors.ant("/wang/**"))//過濾路徑

配置Swagger開關

1.通過enable()方法配置是否啟用swagger，如果是false，swagger將不能在瀏覽器中訪問，可以配合切換test環境和dev環境

   public Docket docket(Environment environment){
        //設定要顯示的環境
        Profiles profiles = Profiles.of("dev","test");
        //判斷是否屬於在此環境當中
        boolean b = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
       .apilnfo(apilnfo)
       .enable(b)
        ...........

2.配置多個分組，可以用groupName()

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

重啟專案檢視即可

Swagger註解

1.實體類配置註釋

@ApiModel("使用者實體類")
public class User {
    @ApiModelProperty("使用者名稱")
    private String name;
    @ApiModelProperty("密碼")
    private String password;
}

注：並不是因為@ApiModel這個註解讓實體顯示在這裡了，而是隻要出現在介面方法的返回值上的實體都會顯示在這裡，而@ApiModel和@ApiModelProperty這兩個註解只是為實體新增註釋的。

@ApiModel為類新增註釋

@ApiModelProperty為類屬性新增註釋

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

例如：

@ApiOperation("王的介面")
@PostMapping("/wang")
@ResponseBody
public String kuang(@ApiParam("這個名字會被返回")String username){
   return username;
}