在使用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