SpringBoot集成swagger-ui以及swagger分組顯示操作
大家好，這篇文章展示下如何在springboot項(xiàng)目中集成swagger-ui。有人說(shuō)，這都是老生常談，網(wǎng)上的例子數(shù)不勝數(shù)。確實(shí)swagger誕生至今已經(jīng)很久了，但是在使用過(guò)程中我遇到一個(gè)問(wèn)題，下面給大家分享下我的使用心得吧。
1.swagger配置類
第一步，需要在pom中引入相應(yīng)的配置，這里使用2.7.0的版本。需要注意的是2.7.0和2.8.0的版本在界面風(fēng)格上差異很大，如果感興趣，可以試試2.8.0以上的版本，我比較青睞使用2.7.0及以下的版本，因?yàn)榻缑姹容^清爽。
第一步 引入pom
<!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
第二步
在代碼中加入相應(yīng)的配置，新建config包，寫入swaggerConfig配置類：
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;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 創(chuàng)建API應(yīng)用
* apiInfo() 增加API相關(guān)信息
* 通過(guò)select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制哪些接口暴露給Swagger來(lái)展現(xiàn)，
* 本例采用指定掃描的包路徑來(lái)定義指定要建立API的目錄。
*
* @return
*/
@Bean
public Docket restApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("標(biāo)準(zhǔn)接口")
.apiInfo(apiInfo("Spring Boot中使用Swagger2構(gòu)建RESTful APIs", "1.0"))
.useDefaultResponseMessages(true)
.forCodeGeneration(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 創(chuàng)建該API的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中）
* 訪問(wèn)地址：http://ip:port/swagger-ui.html
*
* @return
*/
private ApiInfo apiInfo(String title, String version) {
return new ApiInfoBuilder()
.title(title)
.description("更多請(qǐng)關(guān)注: https://jb51.net")
.termsOfServiceUrl("https://jb51.net")
.contact(new Contact("xqnode", "https://jb51.net", "xiaqingweb@163.com"))
.version(version)
.build();
}
}
.apis(RequestHandlerSelectors.basePackage(“com.xqnode.learning.controller”))這個(gè)配置是用來(lái)指定我們的接口層的位置，大家可以根據(jù)你自己項(xiàng)目的實(shí)際情況來(lái)進(jìn)行修改。.apiInfo()是定義一些我們項(xiàng)目的描述信息，可以根據(jù)實(shí)際需要在參數(shù)中修改。需要注意的是配置類的頭部需要加上@Configuration，聲明配置類，以及@EnableSwagger2加載swagger的一些相關(guān)配置。
2.使用swagger
我們?cè)趧偛胖付ǖ慕涌趯邮褂胹wagger來(lái)說(shuō)明接口的使用方法。
import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
import java.io.IOException;
import java.util.Map;
@RestController
@RequestMapping("/api")
@Api(tags = "標(biāo)準(zhǔn)演示接口")
public class ApiController {
@Resource
private ObjectMapper mapper;
@PostMapping("/ps")
@ApiOperation(value = "接受json參數(shù)", notes = "演示json參數(shù)是否接受成功")
public String post(@ApiParam(name = "接收json參數(shù)", defaultValue = "{}")
@RequestBody String json) throws IOException {
Map map = mapper.readValue(json, Map.class);
System.out.println(map);
return json;
}
}
然后我們啟動(dòng)項(xiàng)目，打開http://ip:port/swagger-ui.html:
不輸入任何參數(shù)，點(diǎn)擊try it out!按鈕：
從頁(yè)面上我們可以看到我們?cè)诮涌诘念^部指定的接口類描述(@Api)，以及在接口方法上指定的方法描述(@ApiOperation)，在接口參數(shù)上指定的參數(shù)描述(@ApiParam)都已經(jīng)生效，這都是基于swagger來(lái)實(shí)現(xiàn)的，但是需要注意的是swagger只能提供接口的描述信息。
3.額外的學(xué)習(xí)經(jīng)歷
我在使用swagger的時(shí)候，遇到一個(gè)需求是這樣的，我需要在兩個(gè)接口層都使用swagger，即將兩個(gè)接口層的api分組展示，例如下面這兩個(gè)接口層：
我啟動(dòng)項(xiàng)目后訪問(wèn)swagger頁(yè)面，發(fā)現(xiàn)一個(gè)很奇怪的問(wèn)題，就是other層的接口看不到：
我猜測(cè)原因可能是我在配置類中指定的接口層位置影響了swagger api的顯示。于是我百度了一下，找到一個(gè)解決方案，就是不指定接口層的位置，而指定注解的@RestController
@Bean
public Docket restApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("standard")
.apiInfo(apiInfo("Spring Boot中使用Swagger2構(gòu)建RESTful APIs", "1.0"))
.useDefaultResponseMessages(true)
.forCodeGeneration(false)
.select()
// .apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller"))
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}
swagger界面中出現(xiàn)了另一個(gè)接口的api：
但是這樣的效果并不好。大家試想一下，我們?yōu)槭裁匆獙?duì)接口分層呢？不就是為了將業(yè)務(wù)隔離么，這樣在一個(gè)界面中出現(xiàn)兩個(gè)接口層的api，對(duì)于我們查找接口非常的不方便，也打亂了我們對(duì)接口分層的目的。那么怎么才能將其進(jìn)行隔離開呢？
其實(shí)很簡(jiǎn)單，我們只需要重新定義一個(gè)Docket的bean，在其中指定另外接口層的位置即可：
@Bean
public Docket restApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("其他接口")
.apiInfo(apiInfo("Other APIs", "2.0"))
.select()
.apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.other"))
.paths(PathSelectors.regex("/other.*"))
.build();
}
我們?cè)谶@里指定了第二個(gè)接口層的位置，同時(shí)指定了它的路徑前綴，這樣我們?cè)趕wagger頁(yè)面中就能很方便很清晰的找到它里面的接口了。
接口層1：標(biāo)準(zhǔn)接口
接口層2：其他接口
現(xiàn)在我們只要通過(guò)切換分組，就可以找到我們關(guān)注的接口層的api了。
下面貼出完整的配置類：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 創(chuàng)建API應(yīng)用
* apiInfo() 增加API相關(guān)信息
* 通過(guò)select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制哪些接口暴露給Swagger來(lái)展現(xiàn)，
* 本例采用指定掃描的包路徑來(lái)定義指定要建立API的目錄。
*
* @return
*/
@Bean
public Docket restApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("standard")
.apiInfo(apiInfo("Spring Boot中使用Swagger2構(gòu)建RESTful APIs", "1.0"))
.useDefaultResponseMessages(true)
.forCodeGeneration(false)
.select()
.apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.controller"))
// .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.regex("/api.*"))
.build();
}
@Bean
public Docket restApi2() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName("其他接口")
.apiInfo(apiInfo("Other APIs", "2.0"))
.select()
.apis(RequestHandlerSelectors.basePackage("com.xqnode.learning.other"))
.paths(PathSelectors.regex("/other.*"))
.build();
}
/**
* 創(chuàng)建該API的基本信息（這些基本信息會(huì)展現(xiàn)在文檔頁(yè)面中）
* 訪問(wèn)地址：http://ip:port/swagger-ui.html
*
* @return
*/
private ApiInfo apiInfo(String title, String version) {
return new ApiInfoBuilder()
.title(title)
.description("更多請(qǐng)關(guān)注: https://jb51.net")
.termsOfServiceUrl("https://jb51.net")
.contact(new Contact("xqnode", "https://jb51.net", "xiaqingweb@163.com"))
.version(version)
.build();
}
}
至此，springboot集成swagger2完成，同時(shí)加了一個(gè)餐，還滿意吧？哈哈
以上這篇SpringBoot集成swagger-ui以及swagger分組顯示操作就是小編分享給大家的全部?jī)?nèi)容了，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。
相關(guān)文章
本文將會(huì)給大家講一講Integer這個(gè)包裝類的底層原理。在現(xiàn)在的就業(yè)環(huán)境下，我們需要知其然，還要知其所以然，才能更好地滿足就業(yè)需求，感興趣的小伙伴可以參考閱讀2023-05-05
SpringBoot實(shí)現(xiàn)接口數(shù)據(jù)的加解密功能
這篇文章主要介紹了SpringBoot實(shí)現(xiàn)接口數(shù)據(jù)的加解密功能,對(duì)接口的加密解密操作主要有兩種實(shí)現(xiàn)方式，文中給大家詳細(xì)介紹，需要的朋友可以參考下2019-10-10
下面小編就為大家?guī)?lái)一篇基于java涉及父子類的異常詳解。小編覺(jué)得挺不錯(cuò)的，現(xiàn)在就分享給大家，也給大家做個(gè)參考。一起跟隨小編過(guò)來(lái)看看吧2016-09-09
Intellij IDEA導(dǎo)入JAVA項(xiàng)目并啟動(dòng)(圖文教程)
這篇文章主要介紹了Intellij IDEA導(dǎo)入JAVA項(xiàng)目并啟動(dòng)，文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧2020-08-08
java private關(guān)鍵字用法實(shí)例
這篇文章主要介紹了java private關(guān)鍵字用法實(shí)例,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2019-10-10
Java+Swing實(shí)現(xiàn)中國(guó)象棋游戲
這篇文章將通過(guò)Java+Swing實(shí)現(xiàn)經(jīng)典的中國(guó)象棋游戲。文中可以實(shí)現(xiàn)開始游戲，悔棋，退出等功能。感興趣的小伙伴可以跟隨小編一起動(dòng)手試一試2022-02-02
關(guān)于RequestMapping注解的作用說(shuō)明
這篇文章主要介紹了關(guān)于RequestMapping注解的作用說(shuō)明，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教。2022-01-01
這篇文章主要給大家介紹了關(guān)于Java新特性之Optional類超詳細(xì)介紹的相關(guān)資料,Java8中的Optional類是一個(gè)容器對(duì)象,可以包含null或非null值,文中通過(guò)示例代碼介紹的非常詳細(xì),需要的朋友可以參考下2023-07-07
SpringMvc3+extjs4實(shí)現(xiàn)上傳與下載功能
這篇文章主要為大家詳細(xì)介紹了SpringMvc3+extjs4實(shí)現(xiàn)上傳與下載功能，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2017-06-06
這篇文章主要介紹了Java 字符串壓縮與解壓的開發(fā)記錄,本文通過(guò)實(shí)例代碼給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2022-06-06