SpringBoot3整合Knife4j之保姆级教程

整合Knife4j

1. 介绍：Spring MVC框架集成Swagger2生成Api文档的增强解决方案

整合参考： https://doc.xiaominfo.com/docs/quick-start

2. 新建：创建一个名为web的SpringBoot3项目

3. 依赖：web模块引入knife4j依赖

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>
1
2
3
4
5

3. 配置：在web模块resources目录 application-config.yml文件中添加

# springdoc-openapi项目访问访问地址: http://127.0.0.1:8080/doc.html
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    # path: 配置swagger-ui.html/UI界面的访问路径,默认为/swagger-ui.html
    tags-sorter: alpha
    # tags-sorter: 接口文档中的tags排序规则,默认为alpha,可选值为alpha(按字母顺序排序)或as-is(按照在代码中定义的顺序排序)
    operations-sorter: alpha

  api-docs:
    path: /v3/api-docs
    # path: 配置api-docs的访问路径,默认为/v3/api-docs

  group-configs:
    # group-configs: 配置分组信息
    - group: 'default'
      # group: 分组名称
      paths-to-match: '/**'
      # paths-to-match: 配置要匹配的路径,默认为/**
      packages-to-scan: cn.bytewisehub.pai.web
      # packages-to-scan: 配置要扫描的包的路径,直接配置为Controller类所在的包名即可

# knife4j项目访问访问地址:http://127.0.0.1:8080/doc.html#/home
knife4j:
  enable: true
  # 设置为true以启用Knife4j增强功能,这将再应用程序中启用Knife4j UI
  setting:
    # language: 设置Knife4j UI的语言,默认为zh_cn,可选值为zh_cn或en
    language: zh_cn
  #开启生产环境屏蔽
  production: false
  #是否启用登录认证
  basic:
    enable: true
    username: # 自己设置一个
    password: # 自己设置一个
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

3. 测试：web模块web包下TestController包下新建 Knife4jTestRestController类

注：test目录下新建的非测试类在生成target时会被删掉

4. 设置首页：web模块web包下cofig包下新建 Knife4jConfig类
参考文章：https://blog.csdn.net/2301_78646673/article/details/134791387
package cn.bytewisehub.pai.web.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
        // 接口文档标题
        .info(new Info().title("API接口文档")
              // 接口文档简介
              .description("pai api doc")
              // 接口文档版本
              .version("0.0.1-SNAPSHOT")
              // 开发者联系方式
              .contact(new Contact().name("CSDN柳衣白卿")
                       .email("506567828@qq.com")))
        .externalDocs(new ExternalDocumentation()
                      .description("paicoding api doc")
                      .url("http://127.0.0.1:8888"));
    }
}
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

4. 设置首页：web模块web包下cofig包下新建 Knife4jConfig类

参考文章：https://blog.csdn.net/2301_78646673/article/details/134791387

package cn.bytewisehub.pai.web.config;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
        // 接口文档标题
        .info(new Info().title("API接口文档")
              // 接口文档简介
              .description("pai api doc")
              // 接口文档版本
              .version("0.0.1-SNAPSHOT")
              // 开发者联系方式
              .contact(new Contact().name("CSDN柳衣白卿")
                       .email("506567828@qq.com")))
        .externalDocs(new ExternalDocumentation()
                      .description("paicoding api doc")
                      .url("http://127.0.0.1:8888"));
    }
}
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