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

這篇文章主要講解了“Spring Boot集成接口管理工具Knife4j怎么用”，文中的講解內(nèi)容簡(jiǎn)單清晰，易于學(xué)習(xí)與理解，下面請(qǐng)大家跟著小編的思路慢慢深入，一起來研究和學(xué)習(xí)“Spring Boot集成接口管理工具Knife4j怎么用”吧！

集成過程

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

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

添加依賴

既然是用 Maven 來管理項(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 也是可以通過配置類來指定這些信息。

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();
    }
}

編寫 Controller 層

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

@Api(tags = "測(cè)試模塊")
@RestController
public class DemoController {
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @ApiOperation(value = "入門程序，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)起來，接著到瀏覽器中去打開 http://localhost:8080/doc.html，就會(huì)出現(xiàn)以下的主界面。這里有我們之前在配置類中所設(shè)置的一些接口信息，此外，還對(duì)接口進(jìn)行了統(tǒng)計(jì)。因?yàn)槲覀兇a中只寫了一個(gè) POST 的請(qǐng)求，所以這里統(tǒng)計(jì)出只有一個(gè) POST 請(qǐng)求。

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

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

踩過的坑

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

空指針異常

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

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

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

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

第二種，既然我們都已經(jīng)用上 2.6.x 版本了，那我們就是不想降低版本咋整。此時(shí)，我們只需要在主程序啟動(dòng)類中加上 @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)求路徑未找到

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

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

然后到 IDEA 中一看日志，程序照常運(yùn)行，也沒報(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問識(shí)別。

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

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

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

@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)目，再到瀏覽器中去訪問 http://localhost:8080/doc.html 應(yīng)該就能正常訪問 Knife4j 文檔管理頁(yè)面了。

感謝各位的閱讀，以上就是“Spring Boot集成接口管理工具Knife4j怎么用”的內(nèi)容了，經(jīng)過本文的學(xué)習(xí)后，相信大家對(duì)Spring Boot集成接口管理工具Knife4j怎么用這一問題有了更深刻的體會(huì)，具體使用情況還需要大家實(shí)踐驗(yàn)證。這里是億速云，小編將為大家推送更多相關(guān)知識(shí)點(diǎn)的文章，歡迎關(guān)注！