Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 配置指南

Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 配置指南 | 极客日志

<properties>
    <knife4j.version>4.3.0</knife4j.version>
</properties>
<dependencies>
    <!-- Knife4j OpenAPI3 增强依赖 -->
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
        <version>${knife4j.version}</version>
    </dependency>
</dependencies>

<!-- 需要移除的依赖 -->
<!-- <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency> -->

package com.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import lombok.extern.slf4j.Slf4j;
import javax.annotation.PostConstruct;

@Configuration
@EnableKnife4j // 启用 Knife4j 增强功能
@Slf4j
public class SwaggerConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        log.info("=== 初始化 Knife4j OpenAPI3 配置 ===");
        return new OpenAPI().info(apiInfo());
    }

    private Info apiInfo() {
        return new Info()
                .title("项目名称 API 文档")
                .description("项目描述信息")
                .termsOfService("http://localhost:8080/")
                .contact(new Contact()
                        .name("开发团队")
                        .url("http://localhost:8080/")
                        .email("[email protected]"))
                .version("1.0");
    }

    @PostConstruct
    public void init() {
        log.info("=== Knife4j OpenAPI3 配置初始化完成 ===");
        log.info("文档地址：http://localhost:8080/doc.html");
        log.info("OpenAPI JSON: http://localhost:8080/v3/api-docs");
    }
}

package com.example.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 确保 Knife4j 的静态资源能够正常访问
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

# Spring 配置
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # Spring Boot 2.6+ 必须配置
# Knife4j 配置
knife4j:
  enable: true
  setting:
    language: zh-CN # 中文界面

# Spring 配置
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
# Knife4j 配置
knife4j.enable=true
knife4j.setting.language=zh-CN

	OpenAPI3 注解	说明
	`@Tag`	控制器分类
	`@Operation`	接口操作
	`@Parameter`	参数说明
	`@ApiResponse`	响应说明

@RestController
@RequestMapping("/api/user")
@Tag(name = "用户管理", description = "用户注册、登录、信息管理等接口")
public class UserController {
    @PostMapping("/login")
    @Operation(summary = "用户登录", description = "通过用户名和密码登录系统")
    public Result<LoginVO> login(
            @Parameter(description = "登录参数", required = true)
            @Valid
            @RequestBody LoginDTO loginDTO) {
        // 业务逻辑
    }
}

	OpenAPI3 注解	说明
	`@Schema`	模型说明
	`@Schema`	属性说明

@Data
@Schema(description = "用户登录请求参数")
public class LoginDTO {
    @Schema(description = "用户名", example = "admin", required = true)
    @NotBlank(message = "用户名不能为空")
    private String username;

    @Schema(description = "密码", example = "123456", required = true)
    @NotBlank(message = "密码不能为空")
    private String password;
}

@Data
@Schema(description = "通用返回结果")
public class Result<T> {
    @Schema(description = "状态码", example = "200")
    private Integer code;

    @Schema(description = "提示信息", example = "成功")
    private String msg;

    @Schema(description = "返回数据")
    private T data;
}

// 在 JWT 过滤器或安全配置中
private boolean isPublicUri(String uri) {
    return uri.startsWith("/doc.html") || uri.startsWith("/webjars/") 
           || uri.startsWith("/v3/api-docs") || uri.startsWith("/favicon.ico") 
           || uri.equals("/") || uri.startsWith("/swagger-resources");
}

Spring Boot 版本	推荐 Knife4j 版本	说明
2.5.x	4.1.0 - 4.3.0	稳定兼容
2.6.x	4.1.0 - 4.3.0	需配置 pathmatch
2.7.x	4.3.0	最新稳定

Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 配置指南

1. 环境准备

1.1 确认 Spring Boot 版本

1.2 确认项目结构

2. 依赖配置

2.1 添加 Knife4j 依赖

2.2 移除旧版本 Swagger 依赖（如有）

3. 配置类设置

3.1 创建 Swagger 配置类

3.2 可选：WebMvc 配置（解决静态资源问题）

4. 应用配置文件

4.1 application.yml 配置

4.2 application.properties 配置（可选）

5. 代码注解使用指南

5.1 控制器层注解

控制器示例：

5.2 DTO/实体类注解

DTO 示例：

5.3 响应对象注解

6. 安全配置（如果使用 JWT 等安全框架）

7. 访问和测试

7.1 文档访问地址

7.2 功能特性

8. 常见问题及解决方案

8.1 页面无法访问

8.2 接口文档不显示

8.3 静态资源加载失败

9. 版本兼容性参考

10. 最佳实践建议

更多推荐文章

相关免费在线工具

Spring Boot 2.x 集成 Knife4j (OpenAPI 3) 配置指南

1. 环境准备

1.1 确认 Spring Boot 版本

1.2 确认项目结构

2. 依赖配置

2.1 添加 Knife4j 依赖

2.2 移除旧版本 Swagger 依赖（如有）

3. 配置类设置

3.1 创建 Swagger 配置类

3.2 可选：WebMvc 配置（解决静态资源问题）

4. 应用配置文件

4.1 application.yml 配置

4.2 application.properties 配置（可选）

5. 代码注解使用指南

5.1 控制器层注解

控制器示例：

5.2 DTO/实体类注解

DTO 示例：

5.3 响应对象注解

6. 安全配置（如果使用 JWT 等安全框架）

7. 访问和测试

7.1 文档访问地址

7.2 功能特性

8. 常见问题及解决方案

8.1 页面无法访问

8.2 接口文档不显示

8.3 静态资源加载失败

9. 版本兼容性参考

10. 最佳实践建议

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具