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

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");
    }
}

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

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/");
    }
}

若访问文档地址 http://localhost:8080/doc.html 遇到 Knife4j 文档请求异常的错误提示，可以添加 WebMvc 配置来解决。

4. 应用配置文件

4.1 application.yml 配置

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

4.2 application.properties 配置（可选）

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

5. 代码注解使用指南

5.1 控制器层注解

新版 OpenAPI3 注解

控制器示例：

@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) {
        // 业务逻辑
    }
}

5.2 DTO/实体类注解

新版 OpenAPI3 注解

DTO 示例：

@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;
}

5.3 响应对象注解

@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;
}

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

在安全过滤器中放行 Knife4j 相关路径：

// 在 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");
}

7. 访问和测试

7.1 文档访问地址

• Knife4j 增强文档: http://localhost:8080/doc.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs

7.2 功能特性

• 接口分组管理
• 在线调试
• 接口搜索
• 离线文档导出
• 全局参数设置
• 接口权限控制

8. 常见问题及解决方案

8.1 页面无法访问

1. 检查依赖版本：确认 Knife4j 版本兼容性
2. 检查配置：确认 @EnableKnife4j 注解已添加
3. 清除缓存：浏览器 Ctrl+F5 强制刷新

8.2 接口文档不显示

1. 检查注解：确认使用了正确的 OpenAPI3 注解
2. 检查包扫描：确认控制器在 Spring 扫描路径内
3. 检查安全配置：确认 Knife4j 路径已放行

8.3 静态资源加载失败

1. 添加 WebMvc 配置：配置静态资源处理器
2. 检查路径匹配策略：确认 ant_path_matcher 配置

9. 版本兼容性参考

10. 最佳实践建议

1. 统一响应格式：所有接口使用统一的 Result 包装类
2. 详细接口描述：为每个接口和参数添加清晰的描述
3. 分组管理：按模块对接口进行分组
4. 版本控制：在 API 路径中包含版本号
5. 权限控制：在文档中明确接口的访问权限要求