spring boot集成Knife4j_springboot 2.6.13集成 knife4j 4.0

---

一、Knife4j是什么？

前言：
Spring Boot 版本建议 2.4.0~3.0.0之间
Spring Boot 版本 < 2.4 版本则建议选择Knife4j 4.0之前的版本
该示例springboot版本为2.7.18

Knife4j是一个基于Swagger构建的开源JavaAPI文档工具，它为Java开发者提供了生成、展示和调试API文档的功能。它提供了一套美观且功能强大的界面，可以自动生成API文档，并支持接口分组、参数设置、请求示例、响应模型配置等高级功能。

Knife4j 在更名为Knife4j之前,原来的名称是叫swagger-bootstrap-ui，这是两种不一样风格的Ui,对比情况如下

二、使用步骤

1.引入依赖

#  注意：引入knife4j后会自动引入swagger相关依赖，因此无需再手动引入swagger相关依赖，否则会引起版本冲突
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
            <version>4.0.0</version>
        </dependency>
1
2
3
4
5
6

2.新增相关的配置类

package com.xxxx;

import org.springframework.core.annotation.Order;
import springfox.documentation.service.Contact;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi1")
    @Order(1)
    public Docket defaultApi1() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("用户")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("om.xx.demo.controller.sys"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    @Bean(value = "defaultApi2")
    @Order(2)
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("测试")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.xx.demo.controller.test"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("标题")  //标题
                .contact(new Contact("admin","http://127.0.0.1",""))  //作者
                .description("简介API文档")  //简介
                .termsOfServiceUrl("") //服务URL
                .version("1.0") //版本
                .build();
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

3.添加配置信息

在application.properties或application.yml中配置Knife4j相关的属性（可选，根据需要配置）

     knife4j:
     	 # 增强功能开启
    	 enable: true
    	 # 开启生产环境屏蔽（该选项配置后，无法访问页面）
    	 production: true
    	 # 开启Swagger的Basic认证功能,默认是false，配置后登录才可访问页面
    	 basic:
       		 enable: true
        	 # Basic认证用户名
        	 username: admin
        	 # Basic认证密码
       		 password: 123456
1
2
3
4
5
6
7
8
9
10
11
12

4.新建测试类

package com.xx.demo.controller.test;


import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api( tags = "测试接口")
@RestController
public class HelloController {

    @GetMapping("/test")
    @ApiOperation("查test列表")
    public String test(){
        return "hello";
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

5. 启动项目

启动项目后，访问http://ip:port/doc.html,输入用户名密码后可查看

---

三、其他版本集成时常见异常

1. Failed to start bean ‘documentationPluginsBootstrapper

解决办法:再启动类上加@EnableWebMvc
1

2.访问地址后报404

package com.xx.demo.config;



import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;



@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {


    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24