快捷導(dǎo)航

Spring?Boot?集成接口管理工具?Knife4j

更新時(shí)間：2022年05月23日 09:58:32 作者：??村雨遙????

這篇文章主要介紹了Spring?Boot?集成接口管理工具?Knife4j，首先通過(guò)創(chuàng)建一個(gè)?Spring?Boot?項(xiàng)目展開(kāi)主題，需要的小伙伴可以參考一下

前言

之前介紹了如何在 Spring Boot 中集成 Swagger2 和 Swagger3，對(duì)于我們?nèi)粘５慕涌诠芾硪呀?jīng)夠用了。但是作為一個(gè)顏值黨，無(wú)論是 Swagger2 還是 Swagger3，都難以滿足我們的審美。而且 Swagger2 和 Swagger3 都已經(jīng)好久沒(méi)更新了，更新還是比較慢的。

偶然之間發(fā)現(xiàn)了一個(gè)國(guó)產(chǎn)的接口文檔管理工具 Knife4j，它基于 Swagger 而來(lái)，但是又對(duì) Swagger 進(jìn)行了增強(qiáng)，增加兩個(gè)越來(lái)越多的個(gè)性化需求，可以說(shuō)兼具顏值與實(shí)力了。今天我們就來(lái)看看，如何在 Spring Boot 中集成 Knife4j 這個(gè)接口文檔管理工具。

集成過(guò)程

創(chuàng)建 Spring Boot 項(xiàng)目

既然要在 Spring Boot 中使用 Knife4j，那首先就得創(chuàng)建一個(gè) Spring Boot 項(xiàng)目。當(dāng)然，我在之前已經(jīng)寫(xiě)過(guò)文章介紹如何創(chuàng)建 Spring Boot 項(xiàng)目了，所以這里不再贅述。如果你還對(duì) Spring Boot 創(chuàng)建方式不太熟悉，可以參考我之前的文章：Spring Boot 教程之創(chuàng)建項(xiàng)目的三種方式

添加依賴

既然是用 Maven 來(lái)管理項(xiàng)目依賴，那我們?cè)陧?xiàng)目 pom.xml 中引入 Knife4j 的相關(guān)依賴包，引入代碼如下。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

配置添加

接著在項(xiàng)目中創(chuàng)建一個(gè)配置包 config，用于配置 Swagger 的配置依賴。在這里可以配置掃描的 controller 所在的包，設(shè)置接口文檔的標(biāo)題、描述、作者信息等。

這里其實(shí)和 Swagger2 和 Swagger3 很相似，Swagger 也是可以通過(guò)配置類(lèi)來(lái)指定這些信息。

package com.cunyu.springbootknife4jdemo.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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
@EnableKnife4j
public class Knife4jConfiguration {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()                .apis(RequestHandlerSelectors.basePackage("com.cunyu.springbootknife4jdemo.controller"))
                .paths(PathSelectors.any())
                .build();

    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .description("Kinfe4j 集成測(cè)試文檔")
                .contact(new Contact())
                .version("v1.1.0")
                .title("API測(cè)試文檔")
                .build();
    }
}

編寫(xiě) Controller 層

接著我們編寫(xiě)一個(gè)測(cè)試的 controller，用于在 Knife4j 中展示用，代碼如下。

@Api(tags = "測(cè)試模塊")
@RestController
public class DemoController {
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "入門(mén)程序，Hello World")
    @PostMapping("/helloWorld")
    public ResponseEntity<String> helloWorld(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hello World，" + name);
    }
}

啟動(dòng)測(cè)試

然后將項(xiàng)目啟動(dòng)起來(lái)，接著到瀏覽器中去打開(kāi) http://localhost:8080/doc.html，就會(huì)出現(xiàn)以下的主界面。這里有我們之前在配置類(lèi)中所設(shè)置的一些接口信息，此外，還對(duì)接口進(jìn)行了統(tǒng)計(jì)。因?yàn)槲覀兇a中只寫(xiě)了一個(gè) POST 的請(qǐng)求，所以這里統(tǒng)計(jì)出只有一個(gè) POST 請(qǐng)求。

打開(kāi)具體接口，這里就有我們接口的請(qǐng)求和響應(yīng)的一些情況說(shuō)明。

點(diǎn)擊左側(cè) 調(diào)試 按鈕，我們就可以在 Knife4j 中測(cè)試我們的接口。

踩過(guò)的坑

當(dāng)然，如果你按照以上步驟順利打開(kāi)了 Knife4j 的文檔管理頁(yè)面，那接下來(lái)的內(nèi)容你大可不必了解。但如果你按照上邊步驟搭建過(guò)程中也出現(xiàn)了問(wèn)題，那不妨看看以下是否有你遇到的 Bug。

空指針異常

首先是報(bào)空指針異常，報(bào)錯(cuò)信息如下。

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

經(jīng)過(guò)查詢資料可知，這是因?yàn)?nbsp;Springfox 使用的路徑匹配是基于 AntPathMatcher 的，但是由于我使用的是 Spring Boot 2.6.x 版本，正好這個(gè)版本使用的是 PathPatternMatcher，所以才會(huì)出現(xiàn)這個(gè)問(wèn)題。所以這里主要可以通過(guò)兩種方式來(lái)解決。

第一種，無(wú)可厚非，就是將我們的 Spring Boot 的版本降低，從 2.6.x 降到 2.5.x，此時(shí)就應(yīng)該是可以了，這里可以自己去試一下。

第二種，既然我們都已經(jīng)用上 2.6.x 版本了，那我們就是不想降低版本咋整。此時(shí)，我們只需要在主程序啟動(dòng)類(lèi)中加上 @EnableWebMvc 這個(gè)注解。然后再次啟動(dòng)程序，你就會(huì)發(fā)現(xiàn)啟動(dòng)成功了！

@EnableWebMvc
@SpringBootApplication
public class SpringbootKnife4jDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringbootKnife4jDemoApplication.class, args);
    }
}

請(qǐng)求路徑未找到

一山放過(guò)一山攔，以為翻過(guò)了上面的山，就能成功了。沒(méi)想到出師不利，這不又遇到了報(bào)錯(cuò)請(qǐng)求路徑未找到。

當(dāng)我們成功啟動(dòng)項(xiàng)目后，在瀏覽器中打開(kāi) http://localhost:8080/doc.html，卻沒(méi)想到迎接我們的不是成功界面，而是下面的 Whitelabel Error Page。

然后到 IDEA 中一看日志，程序照常運(yùn)行，也沒(méi)報(bào)錯(cuò)，但是給我們拋出了一個(gè) WARN，警告信息如下：

No mapping for GET /doc.html

這是因?yàn)槲覀優(yōu)榱私鉀Q上面的 Bug 而使用到了 @EnableWebMvc，由于它實(shí)現(xiàn)了 WebMvcConfigurer 接口，所以會(huì)導(dǎo)致我們?cè)L問(wèn)識(shí)別。

這時(shí)候問(wèn)題就來(lái)了，上面又需要這個(gè)注解，但是下面這個(gè)問(wèn)題又不需要，那該怎么辦呢？

其實(shí)很簡(jiǎn)單，既然我們要保留 @EnableWebMvc，那我們?nèi)ヅ渲脗€(gè)規(guī)則不就好了。

在項(xiàng)目的 config 包下，我們新建一個(gè)配置類(lèi) WebMvcConfigurer 記成 WebMvcConfigurationSupport 類(lèi)，接著將 dom.html 過(guò)濾掉即可。

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }
}

完成上述配置后，再去運(yùn)行項(xiàng)目，再到瀏覽器中去訪問(wèn) http://localhost:8080/doc.html 應(yīng)該就能正常訪問(wèn) Knife4j 文檔管理頁(yè)面了。