SpringBoot3.3.0集成Knife4j4.5.0实战

原SpringBoot2.7.18升级至3.3.0之后，Knife4j进行同步升级(Spring Boot 3 只支持OpenAPI3规范)，从原3.0.3(knife4j-spring-boot-starter)版本升级至4.5.0(knife4j-openapi3-jakarta-spring-boot-starter)，以下是升级过程与注意事项等

版本信息

• JDK 21
• Maven 3.9.6
• SpringBoot 3.3.0
• Knife4j 4.5.0（截止2024-06-18最新仍为4.5.0）

一、pom.xml引入依赖

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.3.0</version><!-- 2.7.18↑-->
    <relativePath/>
</parent>

<dependencies>
    ...
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        <version>4.5.0</version>
    </dependency>
    ...
</dependencies>

二、yml中配置

# Knife4j配置
# springdoc-openapi配置
springdoc:
  # get请求多参数时不需要添加额外的@ParameterObject和@Parameter注解
  default-flat-param-object: true
  # 启用swaggerUI
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/swagger-ui.html会自动重定向到swagger页面
    path: /swagger-ui.html
    enabled: true
#    tags-sorter: alpha # 标签的排序方式 alpha:按照子母顺序排序（@ApiSupport注解排序不生效，因此需要设置）
#    operations-sorter: alpha # 接口的排序方式 alpha:按照子母顺序排序（@ApiOperationSupport注解排序生效，因此这里不作设置）
    operations-sorter: order # 设置规则为order，该规则会使用Knife4j的增强排序扩展规则`x-order`
  # 启用文档，默认开启
  api-docs:
    path: /v3/api-docs    #swagger后端请求地址
    enabled: true
# knife4j相关配置 可以不用改
knife4j:
  enable: true    #开启knife4j，无需添加@EnableKnife4j注解
  setting:
    language: ZH_CN   # 中文:ZH_CN 英文:EN
    enable-swagger-models: true
    enable-dynamic-parameter: false
    footer-custom-content: "<strong>Copyright ©️ 2024 Keyidea. All Rights Reversed</strong>"
    enable-footer-custom: true
    enable-footer: true
    enable-document-manage: true
  documents: #文档补充说明
    - name: MarkDown语法说明
      locations: classpath:static/markdown/grammar/*
      group: 01-系统接口 # 此处分组必须使用在Knife4jConfig已存在的分组名group，当存在displayName时，使用displayName名称
    - name: 补充文档
      locations: classpath:static/markdown/others/*
      group: 01-系统接口 # 此处分组必须使用在Knife4jConfig已存在的分组名group，当存在displayName时，使用displayName名称

说明：使用knife4j.documents配置补充文档时，需要注意，文档格式必须为markdown格式，另外，文件存放位置如下

Knife4j补充文档存放位置

实际呈现如下

补充文档

三、Knife4jConfig配置

StatusCode类见附录A

package cn.keyidea.common.config;

import cn.keyidea.common.constant.StatusCode;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.Paths;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.Content;
import io.swagger.v3.oas.models.media.MediaType;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.responses.ApiResponse;
import io.swagger.v3.oas.models.responses.ApiResponses;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Map;

/**
 * Knife4jConfig
 * 注意：分组名称暂时只能使用英文或数字，在4.0.0~4.5.0的Knife4j版本中使用中文分组会出现页面访问异常
 * <p>
 * 解决：（2024-06-18）保持原有分组名group不变，新增displayName中文名称；
 * 特别注意：设置displayName后，knife4j.documents.name配置文档时，需使用displayName名称
 * <p>
 *
 * @author qyd
 * @date 2024-04-13
 */
@Configuration
public class Knife4jConfig {

    private final static Logger logger = LoggerFactory.getLogger(Knife4jConfig.class);

    private static final String SERVICE_URL = "http://127.0.0.1:7004/tj4/doc.html";
    private static final String API_INFO_TITLE = "软件接口文档";
    private static final String API_INFO_VERSION = "V1.0";
    private static final String API_INFO_DESCRIPTION = "Api接口列表";
    private static final String API_INFO_LICENSE = "2024年度内部文档,违拷必究.";

    // 2024集同接口
    @Bean
    public GroupedOpenApi api4() {
        return GroupedOpenApi.builder()
                .group("04-2024-api")
                .displayName("04-2024集同接口")
                .packagesToScan("cn.keyidea.second")
                // 自定义全局响应码
                .addOpenApiCustomizer((this::setCustomStatusCode))
                .build();
    }

    // 2023集同接口
    @Bean
    public GroupedOpenApi api3() {
        return GroupedOpenApi.builder()
                .group("03-2023-api")
                .displayName("03-2023集同接口")
                .packagesToScan("cn.keyidea.control")
                // 自定义全局响应码
                .addOpenApiCustomizer((this::setCustomStatusCode))
                .build();
    }

    // 业务接口
    @Bean
    public GroupedOpenApi api2() {

        return GroupedOpenApi.builder()
                .group("02-business-api")
                .displayName("02-业务接口")
                .packagesToScan("cn.keyidea.business")
                // .pathsToMatch("/v1/**")
                .addOpenApiMethodFilter(method -> method.isAnnotationPresent(io.swagger.v3.oas.annotations.Operation.class))
                // 自定义全局响应码
                .addOpenApiCustomizer((this::setCustomStatusCode))
                .build();
    }

    // 系统接口
    @Bean
    public GroupedOpenApi api1() {
        // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                // 分组名称，使用英文，中文访问异常(使用displayName设置中文名，避免直接使用group设置中文时访问异常)
                .group("01-sys-api")
                .displayName("01-系统接口") // 使用displayName设置中文接口分组名时，group仍不可或缺
                .packagesToScan("cn.keyidea.sys")
                // 自定义全局响应码
                .addOpenApiCustomizer((this::setCustomStatusCode))
                .build();
    }

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title(API_INFO_TITLE)
                        .description(API_INFO_DESCRIPTION)
                        .