Spring?Boot?集成接口管理工具?Knife4j
前言
之前介紹了如何在 Spring Boot 中集成 Swagger2 和 Swagger3，對于我們日常的接口管理已經夠用了。但是作為一個顏值黨，無論是 Swagger2 還是 Swagger3，都難以滿足我們的審美。而且 Swagger2 和 Swagger3 都已經好久沒更新了，更新還是比較慢的。
偶然之間發(fā)現(xiàn)了一個國產的接口文檔管理工具 Knife4j，它基于 Swagger 而來，但是又對 Swagger 進行了增強，增加兩個越來越多的個性化需求，可以說兼具顏值與實力了。今天我們就來看看，如何在 Spring Boot 中集成 Knife4j 這個接口文檔管理工具。
集成過程
創(chuàng)建 Spring Boot 項目
既然要在 Spring Boot 中使用 Knife4j，那首先就得創(chuàng)建一個 Spring Boot 項目。當然，我在之前已經寫過文章介紹如何創(chuàng)建 Spring Boot 項目了，所以這里不再贅述。如果你還對 Spring Boot 創(chuàng)建方式不太熟悉，可以參考我之前的文章：Spring Boot 教程之創(chuàng)建項目的三種方式
添加依賴
既然是用 Maven 來管理項目依賴，那我們在項目 pom.xml 中引入 Knife4j 的相關依賴包，引入代碼如下。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>配置添加
接著在項目中創(chuàng)建一個配置包 config，用于配置 Swagger 的配置依賴。在這里可以配置掃描的 controller 所在的包，設置接口文檔的標題、描述、作者信息等。
這里其實和 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 集成測試文檔")
.contact(new Contact())
.version("v1.1.0")
.title("API測試文檔")
.build();
}
}編寫 Controller 層
接著我們編寫一個測試的 controller，用于在 Knife4j 中展示用，代碼如下。
@Api(tags = "測試模塊")
@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);
}
}啟動測試
然后將項目啟動起來，接著到瀏覽器中去打開 http://localhost:8080/doc.html，就會出現(xiàn)以下的主界面。這里有我們之前在配置類中所設置的一些接口信息，此外，還對接口進行了統(tǒng)計。因為我們代碼中只寫了一個 POST 的請求，所以這里統(tǒng)計出只有一個 POST 請求。
打開具體接口，這里就有我們接口的請求和響應的一些情況說明。
點擊左側 調試 按鈕，我們就可以在 Knife4j 中測試我們的接口。
踩過的坑
當然，如果你按照以上步驟順利打開了 Knife4j 的文檔管理頁面，那接下來的內容你大可不必了解。但如果你按照上邊步驟搭建過程中也出現(xiàn)了問題，那不妨看看以下是否有你遇到的 Bug。
空指針異常
首先是報空指針異常，報錯信息如下。
Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
經過查詢資料可知，這是因為 Springfox 使用的路徑匹配是基于 AntPathMatcher 的，但是由于我使用的是 Spring Boot 2.6.x 版本，正好這個版本使用的是 PathPatternMatcher，所以才會出現(xiàn)這個問題。所以這里主要可以通過兩種方式來解決。
第一種，無可厚非，就是將我們的 Spring Boot 的版本降低，從 2.6.x 降到 2.5.x，此時就應該是可以了，這里可以自己去試一下。
第二種，既然我們都已經用上 2.6.x 版本了，那我們就是不想降低版本咋整。此時，我們只需要在主程序啟動類中加上 @EnableWebMvc 這個注解。然后再次啟動程序，你就會發(fā)現(xiàn)啟動成功了！
@EnableWebMvc
@SpringBootApplication
public class SpringbootKnife4jDemoApplication {
public static void main(String[] args) {
SpringApplication.run(SpringbootKnife4jDemoApplication.class, args);
}
}請求路徑未找到
一山放過一山攔，以為翻過了上面的山，就能成功了。沒想到出師不利，這不又遇到了報錯請求路徑未找到。
當我們成功啟動項目后，在瀏覽器中打開 http://localhost:8080/doc.html，卻沒想到迎接我們的不是成功界面，而是下面的 Whitelabel Error Page。
然后到 IDEA 中一看日志，程序照常運行，也沒報錯，但是給我們拋出了一個 WARN，警告信息如下：
No mapping for GET /doc.html
這是因為我們?yōu)榱私鉀Q上面的 Bug 而使用到了 @EnableWebMvc，由于它實現(xiàn)了 WebMvcConfigurer 接口，所以會導致我們訪問識別。
這時候問題就來了，上面又需要這個注解，但是下面這個問題又不需要，那該怎么辦呢？
其實很簡單，既然我們要保留 @EnableWebMvc，那我們去配置個規(guī)則不就好了。
在項目的 config 包下，我們新建一個配置類 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);
}
}完成上述配置后，再去運行項目，再到瀏覽器中去訪問 http://localhost:8080/doc.html 應該就能正常訪問 Knife4j 文檔管理頁面了。
總結
文章主要講了下如何集成并且進行一個最簡單的接口調試，此外，對于文中集成是所遇到的 Bug，如果你沒有遇到，那么你應該順利集成了
到此這篇關于Spring Boot 集成接口管理工具 Knife4j的文章就介紹到這了,更多相關Spring Boot 集成 Knife4j內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
基于SpringBoot?使用?Flink?收發(fā)Kafka消息的示例詳解
這篇文章主要介紹了基于SpringBoot?使用?Flink?收發(fā)Kafka消息,本文通過示例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下2023-01-01
這篇文章主要介紹了Java 調用Restful API接口的攔截，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2021-09-09
spring boot整合mybatis+mybatis-plus的示例代碼
這篇文章主要介紹了spring boot整合mybatis+mybatis-plus的示例代碼，小編覺得挺不錯的，現(xiàn)在分享給大家，也給大家做個參考。一起跟隨小編過來看看吧2018-01-01
Java數據結構之基于比較的排序算法基本原理及具體實現(xiàn)
最近剛學習完七種比較常見的基于比較的排序算法，感覺比較重要，所以寫個博客記錄一下，通讀本篇對大家的學習或工作具有一定的價值，需要的朋友可以參考下2021-09-09
Java數據結構及算法實例：插入排序 Insertion Sort
這篇文章主要介紹了Java數據結構及算法實例：插入排序 Insertion Sort,本文直接給出實例代碼,代碼中包含詳細注釋,需要的朋友可以參考下2015-06-06
SpringBoot如何讀取xml配置bean(@ImportResource)
這篇文章主要介紹了SpringBoot如何讀取xml配置bean(@ImportResource)，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2022-01-01
這篇文章主要介紹了實體類或對象序列化時,忽略為空屬性的操作，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2021-06-06
詳解springmvc控制登錄用戶session失效后跳轉登錄頁面
本篇文章主要介紹了springmvc控制登錄用戶session失效后跳轉登錄頁面，session一旦失效就需要重新登陸，有興趣的同學可以了解一下。2017-01-01
當我們將項目部署到服務器上時,一般會在jar包的同級目錄下加上application.yml配置文件,這樣可以在不重新?lián)Q包的情況下修改配置,這種方式存在安全隱患,如果配置文件泄露,就會造成數據庫密碼泄露,所以本文給大家介紹了SpringBoot配置文件中敏感信息加密的三種方法2024-05-05
這篇文章主要為大家介紹了Java Spring Bean的生命周期管理，具有一定的參考價值，感興趣的小伙伴們可以參考一下，希望能夠給你帶來幫助2021-12-12