Knife4j?3.0.3?整合SpringBoot?2.6.4的詳細(xì)過程
關(guān)于 swagger 本文不再贅述，網(wǎng)上文章很多。本文要講的是Knife4j3.0.3 整合SpringBoot 2.6.4，因為 knife4j 3.x版本（目前只有這一個版本）和2.x版本還是有一些區(qū)別的，如果配置注解方面使用不當(dāng)，很容易導(dǎo)致文檔頁面打不開。同時，SpringBoot 2.6.4的版本也是相對較高的版本，在SpringBoot 2.4以上的版本和之前的版本還是不一樣的，這個也容易導(dǎo)致一些問題。本文就這兩個版本的整合做一個實戰(zhàn)介紹。
一、引入依賴
<!-- Spring Boot 項目starter,快速使用knife4j增強文檔 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>使用Knife4j3.0.3只需要引入這一個依賴即可，其他的swagger依賴不需要了。
這是Knife4j3.0.3版本的依賴所包含的依賴，可見，swagger的依賴已經(jīng)有了。
二、代碼配置
直接上代碼
package com.dake.common.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.jetbrains.annotations.NotNull;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.spring.web.plugins.WebFluxRequestHandlerProvider;
import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.lang.reflect.Field;
import java.util.List;
import java.util.stream.Collectors;
/**
* Knife4j 3.X 配置類.
* 訪問地址：
* <p>
* Knife4j 訪問首頁：<a href="http://localhost:8090/doc.html#/home">...</a>
* </p>
*
* @author fangqi
* @date 2022-6-27 23:43:39
*/
@EnableKnife4j
@Configuration
@EnableSwagger2
@Import(BeanValidatorPluginsConfiguration.class)
// 在 Swagger 3.X 以下版本報錯時可以加此注解解決，但是在3.X版本以上的，加此注解會導(dǎo)致頁面無法打開
//@EnableWebMvc
public class SwaggerConfig {
private static final String SWAGGER_TITLE = "XXX項目 API 接口文檔";
private static final String VERSION = "3.0.3";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.enable(true)
// .useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.groupName("3.X 版本")
.select()
// 方式一: 配置掃描 所有想在swagger界面的統(tǒng)一管理接口，都必須在此包下
// .apis(RequestHandlerSelectors.basePackage("com.dake.controller"))
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
// 方式二: 只有當(dāng)方法上有 @ApiOperation 注解時才能生成對應(yīng)的接口文檔
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(SwaggerConfig.SWAGGER_TITLE)
.description("# XXX項目API接口文檔簡介")
.termsOfServiceUrl("http://127.0.0.1/#/login")
.contact(new Contact("fangqi", "", "fang_qi170@126.com"))
.version(SwaggerConfig.VERSION)
.build();
}
@Bean
public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
return new BeanPostProcessor() {
@Override
public Object postProcessAfterInitialization(@NotNull Object bean, @NotNull String beanName) throws BeansException {
if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
}
return bean;
}
private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
List<T> copy = mappings.stream()
.filter(mapping -> mapping.getPatternParser() == null)
.collect(Collectors.toList());
mappings.clear();
mappings.addAll(copy);
}
@SuppressWarnings("unchecked")
private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
try {
Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
assert field != null;
field.setAccessible(true);
return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
} catch (IllegalArgumentException | IllegalAccessException e) {
throw new IllegalStateException(e);
}
}
};
}
}三、配置文件
在application.yml文件中，添加如下配置：
springfox:
documentation:
swagger:
v2:
path: /api-docs
use-model-v3: true
knife4j:
# 開啟增強
enable: true
# 開啟登錄認(rèn)證
basic:
enable: true
username: admin
password: 123456解釋：
上面第一個配置是knife4j的配置，下面的配置是開啟增強，打開頁面時需要 輸入賬號密碼，我們這里賬號 是admin，密碼是123456.
四、頁面功能
瀏覽器輸入：
http://localhost:8090/doc.html#/
輸入用戶名和密碼即可看到我們所有的controller和加了注解的實體類。
左側(cè)一共有四個被我們用紅框框柱的頁簽。這個顯示頁面比原先的swagger的頁面風(fēng)格更加美觀，也更加適合國人的使用習(xí)慣。
下面我們就這四個菜單一一講解。
1.主頁
目前我們 看到的就是主頁的信息，也就是我們這個接口文檔的簡單介紹。
2.Swagger Modules
這部分就是我們在項目中定義的實體類，我們點擊打開查看一下。
我們看到這個實際上是層次分明的，不同的實體類類型顯示不同的 顏色，非常美觀，比起原來的swagger好看多了。
我們點開第一個看看實體類的情況。
我們看到，有字段的英文名、中文名和數(shù)據(jù)類型，非常的清晰明了。
要知道，這個不是我們手寫的。是打開頁面直接生成的，哪怕里面的字段變化了，只要我們重啟項目、刷新頁面，這個接口文檔會同步進行變更，使用起來非常方便。以后再和其他同事對接口文檔的時候就非常方便了，給他一個地址加上用戶名密碼，讓他自己玩去，不懂了再來問。前端的小姐姐小哥哥用起來也是賊爽的。
上面的這個實體類我們還可以給他起個中文名，那樣就更好了，當(dāng)然你習(xí)慣英文名也很好。
上面配置我們配置過了，代碼中怎么使用呢？
五、如何使用
1.在controller上加兩個注解：
@Api(tags = "XX管理") @ApiSupport(author = "fangqi", order = 1)
上面一共2個注解，第一個是用來說明這個controller的作用，第二個是用來說明是誰開發(fā)的，其他就是為了讓別人知道這是誰開發(fā)的文檔，到時候方便找到你。后面的那個order指的是這個controller在左邊側(cè)邊欄的展示順序。你想啊，這么多controller，你定義一個，我定義一個，項目稍微多一些代碼，找起來也沒有那么方便。如果我們給他定義一個順序，豈不是美哉？order越小，越靠前。有人說了，大家都定義成1，豈不是亂了？這個當(dāng)然是的，不過不會報錯，都是1，等于都沒用了而已。這個順序呢，其實由項目leader定義會更好一些。最重要的放上面，其他的按照順序排就是了。
到這里有人說了，原來的接口是你fangqi開發(fā)的，現(xiàn)在呢，我要在這個上面加一個功能，也就是加一個請求的方法，到時候別人還是找你，這不合適吧！你說的沒錯，關(guān)于這一點我們可以用另外一個注解來單獨設(shè)置你增加的那個方法的作者。
比如現(xiàn)在有一個queryNameById的方法是fangdake新加的，那我們只需要在這個請求方法上加這個注解就行了。到時候，其他接口還是找fangqi，而你這個方法會找fangdake。
2.方法上加注解
@ApiOperationSupport(author = "fangdake")
我們上面講了，可以給類上加注解，給一個中文的提示，告訴使用者這個controller是干什么的，但是方法上呢？當(dāng)然了，方法上我們一樣可以給一個中文的說明：
@ApiOperation(value = "查詢初始化數(shù)據(jù)", notes = "新增和修改頁面的初始化下拉列表數(shù)據(jù)", tags = "延伸操作")
其中，value標(biāo)簽是指的方法的基本功能；notes就是一個描述性的文字，詳細(xì)的說明；tags呢，其實用處不大，在打開接口文檔的時候它會把你這個方法再展示一份放到你給tags起的名字的這個標(biāo)簽下。你打開延伸操作的時候就能看到你加過tags標(biāo)簽的方法了。其實有點類似于分組一樣，從你原先的controller中又給出了一個分組。個人感覺呢，一般是用來給測試或者領(lǐng)導(dǎo)看的。領(lǐng)導(dǎo)覺得有一二三四五，這五個功能比較重要，他可能偶爾要看看，或者這幾個方法比較重要——其實就是太難了，測試要多次測試，而且問題很多，今天測試玩明天測試。這時你就可以把不同類的不同的幾個方法抽出來放一個單獨的分組，這樣比一個菜單一個菜單的去找方便多了，尤其是有一些方法上面用的不是GetMapping這樣的注解，而是RequestMapping，到時候，每個方法都會在這個菜單下生成很多個測試接口，也就是重復(fù)的，你會很難受。
上圖其實就是2個方法，但是我們打開這個菜單的時候會顯示這么多。因為接口中沒有指定具體的請求方式，都是RequestMapping，所以這個接口文檔的測試功能就把所有的測試方法全部給展現(xiàn)出來了，不管是get、post還是delete等請求。
我們打開一個具體的接口。
可以看到請求參數(shù)和返回參數(shù)清晰明了。之所以會這樣，是因為我們的請求參數(shù)和返回參數(shù)都是對象，而且我們在具體的對象上加了注解，所以才會如此。那如何操作呢，我們來看看。
首先是請求參數(shù)：
@Data
@ApiModel(description = "查詢xxx列表DTO")
public class QueryBiListDTO {
@NotBlank(message = "頁碼不能為空")
@ApiModelProperty(value = "頁碼", required = true)
private Integer pageNo;
@NotBlank(message = "每頁條數(shù)不能為空")
@ApiModelProperty(value = "每頁條數(shù)", required = true)
private Integer pageCount;
@ApiModelProperty(value = "xxid")
private String id;
}返回參數(shù)同請求參數(shù)，是一樣的。
我們看到上面的那個圖片，有一個調(diào)試。我們點擊調(diào)試。
我們啟動項目，上面輸入我們需要的參數(shù)，直接可以調(diào)試了，非常方便。不用像postman一樣，搞來搞去，麻煩死了，而且這個是所有人都能看到的，不用每個人都去搞一份。
六、參數(shù)設(shè)置
有人說了，postman測試的東西可以保存啊！其實這個一樣的。
打開文檔管理：
我們看到默認(rèn)是開啟請求參數(shù)緩存的，也就是說我們剛才請求過一次，下一次再請求的時候，我們剛才輸入的參數(shù)還在，不用每次都輸入很多參數(shù)，這么麻煩。如果是一兩個字段還好，如果是新增編輯，特別是很多字段的大頁面的編輯，每次搞一下，辦個小時過去了。這個接口就很方便了，這次新增時你輸入的值，下次還在。你測試的時候只需要改個別地方就可以了，非常非常方便。
到這了，還有人會說，我們很多時候要從請求頭里面那一些東西，比如token了，userId了，等等。確實，一般是這么操作的。別慌，我們這個接口文檔測試的的時候一樣可以搞定。
比如，你每次需要從請求頭里面獲取到用戶id，那么你可以這里設(shè)置成header，然后輸入userId，然后是userId的具體值。如果你要輸入token，那么就輸入token和具體的值。至于這個token的值嘛，需要你獲取到之后放到這里。
這樣看來，這個接口文檔就不止是接口文檔了，它同時也是測試的工具，保存測試數(shù)據(jù)的工具。至于術(shù)語咱就不bb了，什么這加那加那的綜合體之類的，沒啥意義。
當(dāng)然，如果有人想要你這個測試的數(shù)據(jù)，又不能讓你一個一個的拷貝出來給他，那多難受??！這個文檔支持4種方式的下載。
七、非實體類參數(shù)設(shè)置
上面我們給出的接口文檔的請求參數(shù)都是對象的，我們當(dāng)然知道每個字段什么意思了，當(dāng)時如果是單個字段或者是map呢？用map作為controller的請求參數(shù)的非蠢既壞，但是沒辦法，誰讓人家是用戶呢？
這個也很簡單。
@ApiOperation("修改密碼")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",value = "賬號" , dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "oldPassword",value = "舊密碼" , dataType = "String", paramType = "query"),
@ApiImplicitParam(name = "newPassword",value = "新密碼" , dataType = "String", paramType = "query")
})八、忽略參數(shù)
在我們的新增和編輯頁面，經(jīng)常是編輯只比新增多了一個id，如果此時我們再單獨給新增編輯加一個實體類，其實有一些多余。此時我們只需要指定對應(yīng)的字段忽略掉即可。
@PostMapping("addUser")
@ApiOperation("新增用戶")
@ApiOperationSupport(ignoreParameters = "id") // 忽略掉User中的id屬性，不顯示在文檔中
public void addUser(User user) {
}注意：
ignoreParameters支持以數(shù)組形式添加多個忽略參數(shù)
ignoreParameters支持忽略級聯(lián)對象的參數(shù)，比如User實體類中有個Address類型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "addr.id"即可
如果要忽略的參數(shù)過多，可以使用includeParameters反向配置
如果是以@RequestBody形式接收參數(shù)，那么ignoreParameters中填寫參數(shù)名.要忽略的屬性名即可。
@PostMapping("addUser2")
@ApiOperation("添加用戶2")
@ApiOperationSupport(ignoreParameters = {"user.id", "user.age"})
public void addUser2(@RequestBody User user) {
}注意：
ignoreParameters支持以數(shù)組形式添加多個忽略參數(shù)
ignoreParameters支持忽略級聯(lián)對象的參數(shù)，比如User實體類中有個Address類型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "user.addr.id"即可
如果要忽略的參數(shù)過多，可以使用includeParameters反向配置
九、生產(chǎn)上關(guān)閉knife4j
如果要在生產(chǎn)上關(guān)閉knife4j文檔——生產(chǎn)上肯定要關(guān)閉的，只要在配置文件中配置：
# 開啟屏蔽文檔資源production: true
如果你的項目中只有一個application.yml，則項目上線時會指定profile，也就是prd的環(huán)境，這個時候把屏蔽文檔資源打開即可；如果是多個application文件，比如一個基礎(chǔ)的application.yml，然后一個application-dev.yml，一個application-uat.yml，一個application-prd.yml，那么只要在prd這個文件中添加上面 的配置即可。
到此這篇關(guān)于Knife4j3.0.3整合SpringBoot2.6.4的文章就介紹到這了,更多相關(guān)Knife4j整合SpringBoot內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
IDEA 2019.2.2配置Maven3.6.2打開Maven項目出現(xiàn) Unable to import Maven
這篇文章主要介紹了IDEA 2019.2.2配置Maven3.6.2打開Maven項目出現(xiàn) Unable to import Maven project的問題,本文給大家介紹的非常詳細(xì)，對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值，需要的朋友可以參考下2020-12-12
這篇文章主要介紹了Spring基于注解讀取外部配置文件,文中通過示例代碼介紹的非常詳細(xì)，對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友可以參考下2020-12-12
Java大數(shù)運算BigInteger與進制轉(zhuǎn)換詳解
這篇文章主要介紹了Java大數(shù)運算BigInteger與進制轉(zhuǎn)換詳解,Java 提供了 BigInteger(大整數(shù))類和 BigDecimal(大浮點數(shù))類用于大數(shù)運算,這兩個類都繼承自 Number 類(抽象類),由于 BigInteger 在大數(shù)運算中更常見,需要的朋友可以參考下2023-09-09
這篇文章主要介紹了Java中的同步非阻塞IO模型詳解,同步非阻塞IO模型,我們能夠知道,用戶線程一直發(fā)送請求,內(nèi)核一直都能都夠返回 ,直到內(nèi)核完成準(zhǔn)備數(shù)據(jù)、數(shù)據(jù)拷貝的工作,并且返回成功的指示,在此過程中用戶線程不是阻塞的狀態(tài),需要的朋友可以參考下2024-01-01
使用Java將一個List運用遞歸轉(zhuǎn)成樹形結(jié)構(gòu)案例
這篇文章主要介紹了使用Java將一個List運用遞歸轉(zhuǎn)成樹形結(jié)構(gòu)案例,本文通過詳細(xì)的案例來解釋說明了如何去操作,需要的朋友可以參考下2021-06-06
分頁是常見的一種功能,本文主要介紹了MyBatis-Plus?Page分頁不生效的問題解決,文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2024-07-07
在springboot中注入FilterRegistrationBean不生效的原因
這篇文章主要介紹了在springboot中注入FilterRegistrationBean不生效的原因及解決，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-08-08
Java 中組合模型之對象結(jié)構(gòu)模式的詳解
這篇文章主要介紹了Java 中組合模型之對象結(jié)構(gòu)模式的詳解的相關(guān)資料,希望通過本文能幫助到大家理解應(yīng)用對象結(jié)構(gòu)模型，需要的朋友可以參考下2017-09-09
今天小編就為大家分享一篇關(guān)于Java中對于雙屬性枚舉的使用案例，小編覺得內(nèi)容挺不錯的，現(xiàn)在分享給大家，具有很好的參考價值，需要的朋友一起跟隨小編來看看吧2018-12-12
rocketmq是java編寫的,也就是可以指定啟動參數(shù),下面這篇文章主要給大家介紹了關(guān)于rocketmq中日志文件路徑的配置指南,文中通過實例代碼介紹的非常詳細(xì),需要的朋友可以參考下2023-04-04