Spring Boot 集成接口管理工具 Knife4j

 更新时间:2022年05月23日 09:58:32   作者:​ 村雨遥   ​  
这篇文章主要介绍了Spring Boot 集成接口管理工具 Knife4j,首先通过创建一个 Spring Boot 项目展开主题,需要的小伙伴可以参考一下

前言

之前介绍了如何在 Spring Boot 中集成 Swagger2 和 Swagger3,对于我们日常的接口管理已经够用了。但是作为一个颜值党,无论是 Swagger2 还是 Swagger3,都难以满足我们的审美。而且 Swagger2 和 Swagger3 都已经好久没更新了,更新还是比较慢的。

偶然之间发现了一个国产的接口文档管理工具 Knife4j,它基于 Swagger 而来,但是又对 Swagger 进行了增强,增加两个越来越多的个性化需求,可以说兼具颜值与实力了。今天我们就来看看,如何在 Spring Boot 中集成 Knife4j 这个接口文档管理工具。

集成过程

创建 Spring Boot 项目

既然要在 Spring Boot 中使用 Knife4j,那首先就得创建一个 Spring Boot 项目。当然,我在之前已经写过文章介绍如何创建 Spring Boot 项目了,所以这里不再赘述。如果你还对 Spring Boot 创建方式不太熟悉,可以参考我之前的文章:Spring Boot 教程之创建项目的三种方式

添加依赖

既然是用 Maven 来管理项目依赖,那我们在项目 pom.xml 中引入 Knife4j 的相关依赖包,引入代码如下。

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

配置添加

接着在项目中创建一个配置包 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,就会出现以下的主界面。这里有我们之前在配置类中所设置的一些接口信息,此外,还对接口进行了统计。因为我们代码中只写了一个 POST 的请求,所以这里统计出只有一个 POST 请求。

打开具体接口,这里就有我们接口的请求和响应的一些情况说明。

点击左侧 调试 按钮,我们就可以在 Knife4j 中测试我们的接口。

踩过的坑

当然,如果你按照以上步骤顺利打开了 Knife4j 的文档管理页面,那接下来的内容你大可不必了解。但如果你按照上边步骤搭建过程中也出现了问题,那不妨看看以下是否有你遇到的 Bug

空指针异常

首先是报空指针异常,报错信息如下。

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

经过查询资料可知,这是因为 Springfox 使用的路径匹配是基于 AntPathMatcher 的,但是由于我使用的是 Spring Boot 2.6.x 版本,正好这个版本使用的是 PathPatternMatcher,所以才会出现这个问题。所以这里主要可以通过两种方式来解决。

第一种,无可厚非,就是将我们的 Spring Boot 的版本降低,从 2.6.x 降到 2.5.x,此时就应该是可以了,这里可以自己去试一下。

第二种,既然我们都已经用上 2.6.x 版本了,那我们就是不想降低版本咋整。此时,我们只需要在主程序启动类中加上 @EnableWebMvc 这个注解。然后再次启动程序,你就会发现启动成功了!

@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

这是因为我们为了解决上面的 Bug 而使用到了 @EnableWebMvc,由于它实现了 WebMvcConfigurer 接口,所以会导致我们访问识别。

这时候问题就来了,上面又需要这个注解,但是下面这个问题又不需要,那该怎么办呢?

其实很简单,既然我们要保留 @EnableWebMvc,那我们去配置个规则不就好了。

在项目的 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内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • 深入解析Java编程中的StringBuffer与StringBuider

    深入解析Java编程中的StringBuffer与StringBuider

    这篇文章主要介绍了Java编程中的StringBuffer与StringBuider,是Java入门学习中的基础知识,需要的朋友可以参考下
    2015-09-09
  • 智能手表开发API接口

    智能手表开发API接口

    这篇文章主要介绍了智能手表开发API接口,使用图灵机器人平台接口实现天气预报,非常简单实用,这里推荐给大家。
    2015-03-03
  • Mybatis一对多与多对一查询处理详解

    Mybatis一对多与多对一查询处理详解

    这篇文章主要给大家介绍了关于Mybatis一对多与多对一查询处理的相关资料,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2021-03-03
  • Spring Security OAuth2 实现登录互踢的示例代码

    Spring Security OAuth2 实现登录互踢的示例代码

    这篇文章主要介绍了Spring Security OAuth2实现登录互踢的示例代码,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-04-04
  • SpringCloud FeignClient 超时设置

    SpringCloud FeignClient 超时设置

    FeignClient 默认的超时时间可能不满足你的需求,你可以通过几种方式来自定义这些超时设置,具有一定的参考价值,感兴趣的可以了解一下
    2024-08-08
  • Java的this关键字的使用与方法的重载相关知识

    Java的this关键字的使用与方法的重载相关知识

    这篇文章主要介绍了Java的this关键字的使用与方法的重载相关知识,是Java入门学习中的基础知识,需要的朋友可以参考下
    2015-09-09
  • Quarkus篇入门创建项目搭建debug环境

    Quarkus篇入门创建项目搭建debug环境

    这篇文章主要为大家介绍了Quarkus篇入门创建项目搭建debug环境,先来一套hello world,来搭建基本的运行及调试环境吧
    2022-02-02
  • Java数据结构之实现跳表

    Java数据结构之实现跳表

    今天带大家来学习Java数据结构的相关知识,文中对用Java实现跳表作了非常详细的图文解说及代码示例,对正在学习java的小伙伴们有很好地帮助,需要的朋友可以参考下
    2021-05-05
  • Servlet连接数据库实现用户登录的实现示例

    Servlet连接数据库实现用户登录的实现示例

    本文主要介绍了Servlet连接数据库实现用户登录的实现示例,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2022-06-06
  • MyEclipse10安装Log4E插件

    MyEclipse10安装Log4E插件

    这篇文章主要介绍了MyEclipse10安装Log4E插件的相关资料,需要的朋友可以参考下
    2017-10-10

最新评论