??各位小伙伴們大家好，歡迎跟著小扎扎一起學習【Swagger】這門技術，在本片博客中我對B站狂神的Swagger教程進行一個總結，鑒于 看到就是學到、學到就是賺到 精神，這波依然是血賺 ┗|｀O′|┛

💡Swagger知識點速覽

---

• 🔊 Swagger簡介
• • 🔉 為什么使用Swagger
• 🔊 Swagger的配置
• • 🔉 Spring boot集成Swagger
  • • 🔈 新建一個spring boot項目
    • 🔈 導入兩個依賴
    • 🔈 配置Swagger
  • 🔉 配置Swagger可掃描的接口
  • 🔉 控制Swagger的開關
  • 🔉 設置Swagger的分組
  • 🔉 Swagger的各種注釋
• 🔊 使用Swagger接口測試

🔊 Swagger簡介

🔉 為什么使用Swagger

??這個問題就牽涉到技術的更新迭代了，在之前的后端時代，前端只需要管理靜態頁面，而后端需要使用模板引擎(JSP等)去得數據并加以處理,最后顯示出數據。但是隨著時代的發展，開發慢慢進入了前后端分離的時代，前端和后端分成了兩個相對獨立的團隊來合作開發，這就造成了一個問題：前后端集成聯調的時候，前后端人員無法做到“及時協商，盡早解決”，最終造成問題的集中爆發。

??既然已經發現問題，那么就需要使用一種解決方案來避免這個問題的干擾。做過一個完整項目的小伙伴應該都有所了解，前后端之間的協作基本上都在api接口和數據傳輸上，那么如果api接口能夠統一、數據的格式能夠一致，那么問題也就迎刃而解了。

??于是Swagger應運而生，Swagger可以根據在代碼中使用自定義的注解來生成接口文檔,這樣做的好處是在開發接口時可以通過swagger將接口文檔定義好，方便前后端團隊之間的協作，同時也方便以后的維護。

🔊 Swagger的配置

🔉 Spring boot集成Swagger

🔈 新建一個spring boot項目

🔈 導入兩個依賴

<!--Swagger(開始)-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>
<!--Swagger(結束)-->

🔈 配置Swagger

@Configuration
@EnableSwagger2     // 開啟Swagger2
public class SwaggerConfig {
}

??如果只是使用配置類開啟Swagger的話，它的底層會有一些DEFAULT(默認)的值，開啟之后就可以使用網址http://localhost:8080/swagger-ui.html來訪問這個Swagger的文檔界面。??當然，既然有默認的配置，我們就可以實現定制化的配置覆蓋，依然是在這個配置類中進行修改

@Configuration
@EnableSwagger2     // 開啟Swagger2
public class SwaggerConfig {/***用于定制化配置Docket的bean實例*/@Beanpublic Docket Docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(ApiInfo());}/*** 定制化信息的主要設置處*/private ApiInfo ApiInfo() {// 作者的個人信息Contact contact = new Contact("作者的姓名", "作者的個人社交主頁", "作者的郵箱");return new ApiInfo("標題：Swagger的測試接口文檔","簡介：這是一段簡介，關于接口文檔的簡介","版本號:1.0","網頁：這是一個網頁鏈接",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList<>());}
}

??修改之后的頁面信息就會有一些不一樣，restart項目之后重新訪問ui界面

🔉 配置Swagger可掃描的接口

??這一部分的工作也是在SwaggerConfig配置類中實現，主要就是配置哪些api接口會被Swagger生成接口文檔，生成文檔的api就會在swagger的ui界面上顯示。通過以下.apis和.paths的配置，達到的效果就是之后在com.xiaochen.swagger.controller包下的且映射路徑為/hello的才會生成對應的接口文檔

 @Bean
public Docket Docket() {return new Docket(DocumentationType.SWAGGER_2).select()/*** apis就是配置哪些api可以被掃描* 主要參數可以包括：*  - RequestHandlerSelectors.basePackage()：指定可以掃描的包 參數是包(package)名*  - RequestHandlerSelectors.any()：掃描所有*  - RequestHandlerSelectors.none()：都不掃描*  - RequestHandlerSelectors.withClassAnnotation()：掃描類上注解  參數是注解類的反射對象，eg:@RestController.class*  - RequestHandlerSelectors.withMethodAnnotation()掃描方法上注解  參數是注解類的反射對象，eg:@RequestMapping.class*/.apis(RequestHandlerSelectors.basePackage("com.xiaochen.swagger.controller"))/*** paths就是配置哪些映射路徑下的api可以被掃描* 主要參數可以包括：*  - PathSelectors.ant()：指定映射路徑 主要就是斜杠+單詞或者通配符*  - PathSelectors.any()：掃描所有*  - PathSelectors.none()：都不掃描*  - PathSelectors.regex()：掃描符合正則的所有路徑*/.paths(PathSelectors.ant("/hello")).build().apiInfo(ApiInfo());
}

🔉 控制Swagger的開關

??使用.enable可以控制Swagger的開關，如果關閉了Swagger的話就會導致ui界面無法打開，也就無法查看接口文檔
??那么該如何實現只在開發和測試階段開啟Swagger呢？首先應該先預設一下想要開啟的項目環境，通過Environment 對象來監聽項目的環境與預設的是否一致，最后使用.enable控制Swagger的開關

@Bean
public Docket Docket(Environment environment) {// 預設的項目環境(可設置多個)Profiles profiles = Profiles.of("dev", "test");// 監聽項目的環境與預設的是否一致boolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).enable(flag);
}

🔉 設置Swagger的分組

??在沒有設置Swagger的分組之前，有一個默認的default分組，分組個數的多少就取決于SwaggerConfig 配置類中有多少個Docket 實例，值得注意的是：不能出現同名的分組，即使是未命名的分組(也就是default)也不能重復出現，否則就會報java.lang.IllegalStateException異常

🔉 Swagger的各種注釋

controller層使用到的注解

• @ApiOperation(“注釋”)：加在方法上，注釋這個方法
• @ApiParam(“注釋”)：加在參數前，注釋這個參數

entity層使用到的注解

• @ApiModel(“注釋”)：加在實體類上，注釋整個實體類
• @ApiModelProperty(“注釋”)：加在實體類字段上，注釋這個字段

??model里面是否有這個實體類，并不是取決于是否使用了哪個注解，而是方法的返回值是否包含這個實體類對象，也就是看有沒有一個方法return了這個對象。

🔊 使用Swagger接口測試

這里的使用和postman幾乎一樣，可以借鑒學習