Spring Boot集成swagger

---

文章轉載地址 配套視頻地址

使用Swagger

要求： jdk 1.8+ （否則swagger2無法運行）

步驟：

1、新建一個SpringBoot-web項目

2、添加Maven依賴

<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>

3、編寫HelloController，測試確保運行成功！

4、要使用Swagger，我們需要編寫一個配置類-SwaggerConfig來配置 Swagger

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

5、訪問測試 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

配置Swagger

1、Swagger實例Bean是Docket，所以通過配置Docket實例來配置Swaggger。

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

2、可以通過apiInfo( )屬性配置文檔信息

//配置文檔信息 private ApiInfo apiInfo() {Contact contact = new Contact("聯系人名字", "http://xxx.xxx.com/聯系人訪問鏈接", "聯系人郵箱");return new ApiInfo("Swagger學習", // 標題"學習演示如何配置Swagger", // 描述"v1.0", // 版本"http://terms.service.url/組織鏈接", // 組織鏈接contact, // 聯系人信息"Apach 2.0 許可", // 許可"許可鏈接", // 許可連接new ArrayList<>()// 擴展); }

3、Docket 實例關聯上 apiInfo( )

@Bean public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); }

4、重啟項目，訪問測試 http://localhost:8080/swagger-ui.html 看下效果；

配置掃描接口

1、構建Docket時通過select()方法配置怎么掃描接口。

@Bean public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口.apis(RequestHandlerSelectors.basePackage("com.kulipa.swagger.controller")).build(); }

2、重啟項目測試，由于我們配置根據包的路徑掃描接口，所以我們只能看到一個類
3、除了通過包路徑配置掃描接口外，還可以通過配置其他方式掃描接口，這里注釋一下所有的配置方式：

any() // 掃描所有，項目中的所有接口都會被掃描到 none() // 不掃描接口 // 通過方法上的注解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請求 withMethodAnnotation(final Class<? extends Annotation> annotation) // 通過類上的注解掃描，如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口 withClassAnnotation(final Class<? extends Annotation> annotation) basePackage(final String basePackage) // 根據包路徑掃描接口

4、除此之外，我們還可以配置接口掃描過濾：

@Bean public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口.apis(RequestHandlerSelectors.basePackage("com.kulipa.swagger.controller"))// 配置如何通過path過濾,即這里只掃描請求以/kulipa開頭的接口.paths(PathSelectors.ant("/kulipa/**")).build(); }

5、這里的可選值還有

any() // 任何請求都掃描 none() // 任何請求都不掃描 regex(final String pathRegex) // 通過正則表達式控制 ant(final String antPattern) // 通過ant()控制

配置Swagger開關

1、通過enable()方法配置是否啟用swagger，如果是false，swagger將不能在瀏覽器中訪問了

@Bean public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false) //配置是否啟用Swagger，如果是false，在瀏覽器將無法訪問.select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口.apis(RequestHandlerSelectors.basePackage("com.kulipa.swagger.controller"))// 配置如何通過path過濾,即這里只掃描請求以/kulipa開頭的接口.paths(PathSelectors.ant("/kulipa/**")).build(); }

2、如何動態配置當項目處于test、dev環境時顯示swagger，處于prod時不顯示？

@Bean public Docket docket(Environment environment) {// 設置要顯示swagger的環境Profiles of = Profiles.of("dev", "test");// 判斷當前是否處于該環境// 通過 enable() 接收此參數判斷是否要顯示boolean b = environment.acceptsProfiles(of);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(b) //配置是否啟用Swagger，如果是false，在瀏覽器將無法訪問.select()// 通過.select()方法，去配置掃描接口,RequestHandlerSelectors配置如何掃描接口.apis(RequestHandlerSelectors.basePackage("com.kulipa.swagger.controller"))// 配置如何通過path過濾,即這里只掃描請求以/kulipa開頭的接口.paths(PathSelectors.ant("/kulipa/**")).build(); }

3、可以在項目中增加一個dev的配置文件查看效果！

配置API分組

1、如果沒有配置分組，默認是default。通過groupName()方法即可配置分組：

@Bean public Docket docket(Environment environment) {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName("hello") // 配置分組// 省略配置.... }

2、重啟項目查看分組
3、如何配置多個分組？配置多個分組只需要配置多個docket即可：

@Bean public Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("B"); } @Bean public Docket docket3(){return new Docket(DocumentationType.SWAGGER_2).groupName("C"); }

4、重啟項目查看即可

實體配置

1、新建一個實體類

@ApiModel("用戶實體") public class User {@ApiModelProperty("用戶名")public String username;@ApiModelProperty("密碼")public String password; }

2、只要這個實體在請求接口的返回值上（即使是泛型），都能映射到實體項中：

@RequestMapping("/getUser") public User getUser(){return new User(); }

3、重啟查看測試
注：并不是因為@ApiModel這個注解讓實體顯示在這里了，而是只要出現在接口方法的返回值上的實體都會顯示在這里，而@ApiModel和@ApiModelProperty這兩個注解只是為實體添加注釋的。
@ApiModel為類添加注釋
@ApiModelProperty為類屬性添加注釋

常用注解

Swagger的所有注解定義在io.swagger.annotations包下
下面列一些經常用到的，未列舉出來的可以另行查閱說明：

Swagger注解簡單說明

@Api(tags = “xxx模塊說明”)	作用在模塊類上
@ApiOperation(“xxx接口說明”)	作用在接口方法上
@ApiModel(“xxxPOJO說明”)	作用在模型類上：如VO、BO
@ApiModelProperty(value = “xxx屬性說明”,hidden = true)	作用在類方法和屬性上，hidden設置為true可以隱藏該屬性
@ApiParam(“xxx參數說明”)	作用在參數、方法和字段上，類似@ApiModelProperty

我們也可以給請求的接口配置一些注釋

@ApiOperation("Kulipa的接口") @PostMapping("/Kulipa") @ResponseBody public String Kulipa(@ApiParam("這個名字會被返回")String username){return username; }

這樣的話，可以給一些比較難理解的屬性或者接口，增加一些配置信息，讓人更容易閱讀！

相較于傳統的Postman或Curl方式測試接口，使用swagger簡直就是傻瓜式操作，不需要額外說明文檔(寫得好本身就是文檔)而且更不容易出錯，只需要錄入數據然后點擊Execute，如果再配合自動化框架，可以說基本就不需要人為操作了。

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

拓展：其他皮膚

我們可以導入不同的包實現不同的皮膚定義：
1、默認的 訪問 http://localhost:8080/swagger-ui.html

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version> </dependency>

2、bootstrap-ui 訪問 http://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html--> <dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version> </dependency>

3、Layui-ui 訪問 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html--> <dependency><groupId>com.github.caspar-chen</groupId><artifactId>swagger-ui-layer</artifactId><version>1.1.3</version> </dependency>

4、mg-ui 訪問 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html--> <dependency><groupId>com.zyplayer</groupId><artifactId>swagger-mg-ui</artifactId><version>1.0.6</version> </dependency>

總結

以上是生活随笔為你收集整理的[3]、Swagger——解决前后端打架问题的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。