關(guān)于 swagger 本文不再贅述，網(wǎng)上文章很多。本文要講的是Knife4j3.0.3 整合SpringBoot 2.6.4，因?yàn)?knife4j 3.x版本（目前只有這一個(gè)版本）和2.x版本還是有一些區(qū)別的，如果配置注解方面使用不當(dāng)，很容易導(dǎo)致文檔頁(yè)面打不開(kāi)。同時(shí)，SpringBoot 2.6.4的版本也是相對(duì)較高的版本，在SpringBoot 2.4以上的版本和之前的版本還是不一樣的，這個(gè)也容易導(dǎo)致一些問(wèn)題。本文就這兩個(gè)版本的整合做一個(gè)實(shí)戰(zhàn)介紹。

一、引入依賴(lài)

<!-- Spring Boot 項(xiàng)目starter,快速使用knife4j增強(qiáng)文檔 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>3.0.3</version>
</dependency>

使用Knife4j3.0.3只需要引入這一個(gè)依賴(lài)即可，其他的swagger依賴(lài)不需要了。

這是Knife4j3.0.3版本的依賴(lài)所包含的依賴(lài)，可見(jiàn)，swagger的依賴(lài)已經(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 配置類(lèi).
 * 訪(fǎng)問(wèn)地址：
 * <p>
 *     Knife4j 訪(fǎng)問(wèn)首頁(yè)：<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 以下版本報(bào)錯(cuò)時(shí)可以加此注解解決，但是在3.X版本以上的，加此注解會(huì)導(dǎo)致頁(yè)面無(wú)法打開(kāi)
//@EnableWebMvc
public class SwaggerConfig {
 
    private static final String SWAGGER_TITLE = "XXX項(xiàng)目 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 注解時(shí)才能生成對(duì)應(yīng)的接口文檔
                // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(SwaggerConfig.SWAGGER_TITLE)
                .description("# XXX項(xiàng)目API接口文檔簡(jiǎn)介")
                .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:
  # 開(kāi)啟增強(qiáng)
  enable: true
  # 開(kāi)啟登錄認(rèn)證
  basic:
    enable: true
    username: admin
    password: 123456

解釋?zhuān)?/p>

上面第一個(gè)配置是knife4j的配置，下面的配置是開(kāi)啟增強(qiáng)，打開(kāi)頁(yè)面時(shí)需要 輸入賬號(hào)密碼，我們這里賬號(hào) 是admin，密碼是123456.

四、頁(yè)面功能

瀏覽器輸入：

http://localhost:8090/doc.html#/

輸入用戶(hù)名和密碼即可看到我們所有的controller和加了注解的實(shí)體類(lèi)。

左側(cè)一共有四個(gè)被我們用紅框框柱的頁(yè)簽。這個(gè)顯示頁(yè)面比原先的swagger的頁(yè)面風(fēng)格更加美觀(guān)，也更加適合國(guó)人的使用習(xí)慣。

下面我們就這四個(gè)菜單一一講解。

1.主頁(yè)

目前我們 看到的就是主頁(yè)的信息，也就是我們這個(gè)接口文檔的簡(jiǎn)單介紹。

2.Swagger Modules

這部分就是我們?cè)陧?xiàng)目中定義的實(shí)體類(lèi)，我們點(diǎn)擊打開(kāi)查看一下。

我們看到這個(gè)實(shí)際上是層次分明的，不同的實(shí)體類(lèi)類(lèi)型顯示不同的 顏色，非常美觀(guān)，比起原來(lái)的swagger好看多了。

我們點(diǎn)開(kāi)第一個(gè)看看實(shí)體類(lèi)的情況。

我們看到，有字段的英文名、中文名和數(shù)據(jù)類(lèi)型，非常的清晰明了。

要知道，這個(gè)不是我們手寫(xiě)的。是打開(kāi)頁(yè)面直接生成的，哪怕里面的字段變化了，只要我們重啟項(xiàng)目、刷新頁(yè)面，這個(gè)接口文檔會(huì)同步進(jìn)行變更，使用起來(lái)非常方便。以后再和其他同事對(duì)接口文檔的時(shí)候就非常方便了，給他一個(gè)地址加上用戶(hù)名密碼，讓他自己玩去，不懂了再來(lái)問(wèn)。前端的小姐姐小哥哥用起來(lái)也是賊爽的。

上面的這個(gè)實(shí)體類(lèi)我們還可以給他起個(gè)中文名，那樣就更好了，當(dāng)然你習(xí)慣英文名也很好。

上面配置我們配置過(guò)了，代碼中怎么使用呢？

五、如何使用

1.在controller上加兩個(gè)注解：

@Api(tags = "XX管理")
@ApiSupport(author = "fangqi", order = 1)

上面一共2個(gè)注解，第一個(gè)是用來(lái)說(shuō)明這個(gè)controller的作用，第二個(gè)是用來(lái)說(shuō)明是誰(shuí)開(kāi)發(fā)的，其他就是為了讓別人知道這是誰(shuí)開(kāi)發(fā)的文檔，到時(shí)候方便找到你。后面的那個(gè)order指的是這個(gè)controller在左邊側(cè)邊欄的展示順序。你想啊，這么多controller，你定義一個(gè)，我定義一個(gè)，項(xiàng)目稍微多一些代碼，找起來(lái)也沒(méi)有那么方便。如果我們給他定義一個(gè)順序，豈不是美哉？order越小，越靠前。有人說(shuō)了，大家都定義成1，豈不是亂了？這個(gè)當(dāng)然是的，不過(guò)不會(huì)報(bào)錯(cuò)，都是1，等于都沒(méi)用了而已。這個(gè)順序呢，其實(shí)由項(xiàng)目leader定義會(huì)更好一些。最重要的放上面，其他的按照順序排就是了。

到這里有人說(shuō)了，原來(lái)的接口是你fangqi開(kāi)發(fā)的，現(xiàn)在呢，我要在這個(gè)上面加一個(gè)功能，也就是加一個(gè)請(qǐng)求的方法，到時(shí)候別人還是找你，這不合適吧！你說(shuō)的沒(méi)錯(cuò)，關(guān)于這一點(diǎn)我們可以用另外一個(gè)注解來(lái)單獨(dú)設(shè)置你增加的那個(gè)方法的作者。

比如現(xiàn)在有一個(gè)queryNameById的方法是fangdake新加的，那我們只需要在這個(gè)請(qǐng)求方法上加這個(gè)注解就行了。到時(shí)候，其他接口還是找fangqi，而你這個(gè)方法會(huì)找fangdake。

2.方法上加注解

@ApiOperationSupport(author = "fangdake")

我們上面講了，可以給類(lèi)上加注解，給一個(gè)中文的提示，告訴使用者這個(gè)controller是干什么的，但是方法上呢？當(dāng)然了，方法上我們一樣可以給一個(gè)中文的說(shuō)明：

@ApiOperation(value = "查詢(xún)初始化數(shù)據(jù)", 
notes = "新增和修改頁(yè)面的初始化下拉列表數(shù)據(jù)", 
tags = "延伸操作")

其中，value標(biāo)簽是指的方法的基本功能；notes就是一個(gè)描述性的文字，詳細(xì)的說(shuō)明；tags呢，其實(shí)用處不大，在打開(kāi)接口文檔的時(shí)候它會(huì)把你這個(gè)方法再展示一份放到你給tags起的名字的這個(gè)標(biāo)簽下。你打開(kāi)延伸操作的時(shí)候就能看到你加過(guò)tags標(biāo)簽的方法了。其實(shí)有點(diǎn)類(lèi)似于分組一樣，從你原先的controller中又給出了一個(gè)分組。個(gè)人感覺(jué)呢，一般是用來(lái)給測(cè)試或者領(lǐng)導(dǎo)看的。領(lǐng)導(dǎo)覺(jué)得有一二三四五，這五個(gè)功能比較重要，他可能偶爾要看看，或者這幾個(gè)方法比較重要——其實(shí)就是太難了，測(cè)試要多次測(cè)試，而且問(wèn)題很多，今天測(cè)試玩明天測(cè)試。這時(shí)你就可以把不同類(lèi)的不同的幾個(gè)方法抽出來(lái)放一個(gè)單獨(dú)的分組，這樣比一個(gè)菜單一個(gè)菜單的去找方便多了，尤其是有一些方法上面用的不是GetMapping這樣的注解，而是RequestMapping，到時(shí)候，每個(gè)方法都會(huì)在這個(gè)菜單下生成很多個(gè)測(cè)試接口，也就是重復(fù)的，你會(huì)很難受。

上圖其實(shí)就是2個(gè)方法，但是我們打開(kāi)這個(gè)菜單的時(shí)候會(huì)顯示這么多。因?yàn)榻涌谥袥](méi)有指定具體的請(qǐng)求方式，都是RequestMapping，所以這個(gè)接口文檔的測(cè)試功能就把所有的測(cè)試方法全部給展現(xiàn)出來(lái)了，不管是get、post還是delete等請(qǐng)求。

我們打開(kāi)一個(gè)具體的接口。

可以看到請(qǐng)求參數(shù)和返回參數(shù)清晰明了。之所以會(huì)這樣，是因?yàn)槲覀兊恼?qǐng)求參數(shù)和返回參數(shù)都是對(duì)象，而且我們?cè)诰唧w的對(duì)象上加了注解，所以才會(huì)如此。那如何操作呢，我們來(lái)看看。

首先是請(qǐng)求參數(shù)：

@Data
@ApiModel(description = "查詢(xún)xxx列表DTO")
public class QueryBiListDTO {
 
    @NotBlank(message = "頁(yè)碼不能為空")
    @ApiModelProperty(value = "頁(yè)碼", required = true)
    private Integer pageNo;
 
    @NotBlank(message = "每頁(yè)條數(shù)不能為空")
    @ApiModelProperty(value = "每頁(yè)條數(shù)", required = true)
    private Integer pageCount;
 
    @ApiModelProperty(value = "xxid")
    private String id;
}

返回參數(shù)同請(qǐng)求參數(shù)，是一樣的。

我們看到上面的那個(gè)圖片，有一個(gè)調(diào)試。我們點(diǎn)擊調(diào)試。

我們啟動(dòng)項(xiàng)目，上面輸入我們需要的參數(shù)，直接可以調(diào)試了，非常方便。不用像postman一樣，搞來(lái)搞去，麻煩死了，而且這個(gè)是所有人都能看到的，不用每個(gè)人都去搞一份。

六、參數(shù)設(shè)置

有人說(shuō)了，postman測(cè)試的東西可以保存??！其實(shí)這個(gè)一樣的。

打開(kāi)文檔管理：

我們看到默認(rèn)是開(kāi)啟請(qǐng)求參數(shù)緩存的，也就是說(shuō)我們剛才請(qǐng)求過(guò)一次，下一次再請(qǐng)求的時(shí)候，我們剛才輸入的參數(shù)還在，不用每次都輸入很多參數(shù)，這么麻煩。如果是一兩個(gè)字段還好，如果是新增編輯，特別是很多字段的大頁(yè)面的編輯，每次搞一下，辦個(gè)小時(shí)過(guò)去了。這個(gè)接口就很方便了，這次新增時(shí)你輸入的值，下次還在。你測(cè)試的時(shí)候只需要改個(gè)別地方就可以了，非常非常方便。

到這了，還有人會(huì)說(shuō)，我們很多時(shí)候要從請(qǐng)求頭里面那一些東西，比如token了，userId了，等等。確實(shí)，一般是這么操作的。別慌，我們這個(gè)接口文檔測(cè)試的的時(shí)候一樣可以搞定。

比如，你每次需要從請(qǐng)求頭里面獲取到用戶(hù)id，那么你可以這里設(shè)置成header，然后輸入userId，然后是userId的具體值。如果你要輸入token，那么就輸入token和具體的值。至于這個(gè)token的值嘛，需要你獲取到之后放到這里。

這樣看來(lái)，這個(gè)接口文檔就不止是接口文檔了，它同時(shí)也是測(cè)試的工具，保存測(cè)試數(shù)據(jù)的工具。至于術(shù)語(yǔ)咱就不bb了，什么這加那加那的綜合體之類(lèi)的，沒(méi)啥意義。

當(dāng)然，如果有人想要你這個(gè)測(cè)試的數(shù)據(jù)，又不能讓你一個(gè)一個(gè)的拷貝出來(lái)給他，那多難受啊！這個(gè)文檔支持4種方式的下載。

七、非實(shí)體類(lèi)參數(shù)設(shè)置

上面我們給出的接口文檔的請(qǐng)求參數(shù)都是對(duì)象的，我們當(dāng)然知道每個(gè)字段什么意思了，當(dāng)時(shí)如果是單個(gè)字段或者是map呢？用map作為controller的請(qǐng)求參數(shù)的非蠢既壞，但是沒(méi)辦法，誰(shuí)讓人家是用戶(hù)呢？

這個(gè)也很簡(jiǎn)單。

@ApiOperation("修改密碼")
    @ApiImplicitParams({
	@ApiImplicitParam(name = "username",value = "賬號(hào)" , dataType = "String", paramType = "query"),		
	@ApiImplicitParam(name = "oldPassword",value = "舊密碼" , dataType = "String", paramType = "query"),
	@ApiImplicitParam(name = "newPassword",value = "新密碼" , dataType = "String", paramType = "query")
	})

八、忽略參數(shù)

在我們的新增和編輯頁(yè)面，經(jīng)常是編輯只比新增多了一個(gè)id，如果此時(shí)我們?cè)賳为?dú)給新增編輯加一個(gè)實(shí)體類(lèi)，其實(shí)有一些多余。此時(shí)我們只需要指定對(duì)應(yīng)的字段忽略掉即可。

@PostMapping("addUser")
@ApiOperation("新增用戶(hù)")
@ApiOperationSupport(ignoreParameters = "id") // 忽略掉User中的id屬性，不顯示在文檔中
public void addUser(User user) {
 
}

注意：

ignoreParameters支持以數(shù)組形式添加多個(gè)忽略參數(shù)
ignoreParameters支持忽略級(jí)聯(lián)對(duì)象的參數(shù)，比如User實(shí)體類(lèi)中有個(gè)Address類(lèi)型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "addr.id"即可
如果要忽略的參數(shù)過(guò)多，可以使用includeParameters反向配置

如果是以@RequestBody形式接收參數(shù)，那么ignoreParameters中填寫(xiě)參數(shù)名.要忽略的屬性名即可。

@PostMapping("addUser2")
@ApiOperation("添加用戶(hù)2")
@ApiOperationSupport(ignoreParameters = {"user.id", "user.age"})
public void addUser2(@RequestBody User user) {
 
}

注意：

ignoreParameters支持以數(shù)組形式添加多個(gè)忽略參數(shù)
ignoreParameters支持忽略級(jí)聯(lián)對(duì)象的參數(shù)，比如User實(shí)體類(lèi)中有個(gè)Address類(lèi)型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "user.addr.id"即可
如果要忽略的參數(shù)過(guò)多，可以使用includeParameters反向配置

九、生產(chǎn)上關(guān)閉knife4j

如果要在生產(chǎn)上關(guān)閉knife4j文檔——生產(chǎn)上肯定要關(guān)閉的，只要在配置文件中配置：

# 開(kāi)啟屏蔽文檔資源production: true

如果你的項(xiàng)目中只有一個(gè)application.yml，則項(xiàng)目上線(xiàn)時(shí)會(huì)指定profile，也就是prd的環(huán)境，這個(gè)時(shí)候把屏蔽文檔資源打開(kāi)即可；如果是多個(gè)application文件，比如一個(gè)基礎(chǔ)的application.yml，然后一個(gè)application-dev.yml，一個(gè)application-uat.yml，一個(gè)application-prd.yml，那么只要在prd這個(gè)文件中添加上面 的配置即可。

到此這篇關(guān)于Knife4j3.0.3整合SpringBoot2.6.4的文章就介紹到這了,更多相關(guān)Knife4j整合SpringBoot內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！