SpringBoot3配置Knife4j增强【真保姆级教程】

在使用swagger时，springboot的版本升级到3以上后，如果再按照之前的配置使用knife4j增强，访问时地址可以打开，但是会报一个404的错误，显示knife4j文档请求异常，这篇文章可以解决这个问题。

首先介绍一下现在项目各种配置的版本：

• SpringBoot版本：3.4.1
• Maven版本：3.6.1
• Knife4j版本：4.5.0
• JDK版本：17

1、依赖引入

创建好项目后，直接引入依赖，这里仅需要一个knife4j的依赖即可，由于目前最新版本为4.5.0，不能保证所有人此版本都可用，如果出现问题，可以下载多个版本使用。

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

2、yml配置

在yml中配置springdoc和knife4j相关配置，这里为了方便，仅配置基础配置，如有需要可以单独去了解一下。

springdoc:
  api-docs:
    enabled: true # 启用API文档
  swagger-ui:
    path: /swagger-ui.html # Swagger UI的路径
knife4j:
  enable: true 

3、Knife4j配置类

直接按照下面的代码进行细微调整即可，例如title等，如果不修改也可以，对knife4j的使用没什么影响。

package com.example.config;

import io.swagger.v3.oas.models.OpenAPI;
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 org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Knife4j整合Swagger3 Api接口文档配置类
 * @author Thomas
 */
@Configuration
public class Knife4jConfig {

    /**
     * 创建了一个api接口的分组
     * 除了配置文件方式创建分组，也可以通过注册bean创建分组
     */
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                // 分组名称
                .group("app-api")
                // 接口请求路径规则
                .pathsToMatch("/**")
                .build();
    }

    /**
     * 配置基本信息
     */
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        // 标题
                        .title("接口文档")
                        // 描述Api接口文档的基本信息
                        .description("后端服务接口")
                        // 版本
                        .version("v1.0.0")
                        // 设置OpenAPI文档的联系信息，姓名，邮箱。
                        .contact(new Contact().name("Thomas").email("2907205361@qq.com"))
                        // 设置OpenAPI文档的许可证信息，包括许可证名称为"Apache 2.0"，许可证URL为"http://springdoc.org"。
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );
    }
}

4、注解使用

# Controller注解更新
@Api → @Tag
@ApiSort → @ApiSupport

# 类接口注解更新
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

# 实体类注解更新
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiParam → @Parameter

使用示例：

这里是定义了一个简单的Controller

package com.example.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.PromptTemplate;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.core.io.Resource;
import org.springframework.web.bind.annotation.*;
import reactor.core.publisher.Flux;

import java.util.Map;

/**
 * @program: demo
 * @description:
 * @author: Thomas
 * @create: 2024-12-23 13:55
 **/

@RestController
@RequestMapping("/ai")
@CrossOrigin(origins = "*")
@Tag(name = "通义大模型RAG", description = "通义大模型问答")
public class ChatController {

    private final ChatClient chatClient;

    @Value("classpath:correct-and-expand.st")
    Resource resource;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat")
    @Operation(summary = "通义-普通问答", description = "通义-普通问答")
    public String chat(String input) {
        return this.chatClient.prompt()
                .user(input)
                .call()
                .content();
    }
}

浏览器访问：http://localhost:8080/doc.html

swagger也可以访问：http://localhost:8080/swagger-ui/index.html