跳至主要內容

Knife4j - API 文档增强工具

JustQ2025/11/30大约 12 分钟Java-learningJavaWebjavaframeworkapiswaggertutorialintermediatespringboot

Knife4j

Knife4j是一款集Swagger 2及OpenAPI 3为一体的API文档增强工具，在Spring Boot 3中，由于Spring Boot 3仅支持OpenAPI 3规范，并且要求JDK版本至少为17，因此配置方式与旧版本有所不同。

📊 注解差异对比总览

注解用途Spring Boot 2.x (Swagger 2 注解)Spring Boot 3.x (OpenAPI 3 注解)说明
描述Controller类@Api(tags = "用户接口")@Tag(name = "用户接口")用于对接口进行分组。注意：OpenAPI 3 的 @Tag 不能替换 Swagger 2 的 @Api，因为它们作用不同。
描述接口方法@ApiOperation("获取用户")@Operation(summary = "获取用户", description = "...")描述接口的具体信息。
描述响应@ApiResponse(code = 200, message = "成功")@ApiResponse(responseCode = "200", description = "成功")注意属性名从 code 变为了 responseCode。
描述请求参数@ApiParam("用户ID")@Parameter(description = "用户ID")用于描述 @RequestParam, @PathVariable 等参数。
描述模型(实体类)@ApiModel("用户实体")@Schema(description = "用户实体")在类上使用。
描述模型属性@ApiModelProperty("用户名")@Schema(description = "用户名")

在Springboot3中的用法

下面详细讲解在Spring Boot 3中如何使用Knife4j。

📦 添加项目依赖

在项目的pom.xml文件中添加Knife4j的Starter依赖。Spring Boot 3需使用对应的Jakarta版本Starter。

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version> <!-- 亦可使用4.5.0等更高版本 -->
</dependency>

⚙️ 配置Knife4j与SpringDoc

配置Knife4j主要有两种方式：通过配置文件（推荐，更简洁）或通过Java配置类。不需要静态资源映射配置了。

1. 通过配置文件配置 (YAML示例)

在application.yml中进行配置。以下配置示例包含了SpringDoc和Knife4j增强的基本设置：

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.yourpackage.controller  # 替换为你的Controller包路径
# knife4j的增强配置
knife4j:
  enable: true  # 开启Knife4j增强功能
  setting:
    language: zh_cn  # 设置界面语言为中文

配置说明：

  • springdoc.packages-to-scan：指定扫描API接口的包路径，这是必须修改的项。
  • knife4j.enable：设置为true以启用Knife4j的增强功能，否则访问/doc.html将看到原生Swagger界面。
  • knife4j.setting.language：可设置界面语言，例如zh_cn为中文。

**注意：**如果做了拦截要放行：主要看拦截器拦截了什么，如果只拦截controller路径就放行controller路径，如果拦截所有还要放行其他的静态资源路径。
springboot3:

registry.addInterceptor(jwtTokenInterceptor)
                .addPathPatterns("/**")  // 拦截所有请求
                .excludePathPatterns( //不拦截的内容
                        "/user/login",          // 登录
    // 不是controller的会被放行，因为jwtIntercepter放行非Controller内容。
                     //   "/doc.html",             // knife4j文档，
                     //  "/webjars/**",           // knife4j资源
                        "/swagger-resources/**",    // swagger资源，spring doc的controller要放行所有才能看见
                     // "/v2/api-docs",          // swagger2文档
                         "/v3/api-docs/**",          // swagger3文档，spring doc的controller要放行所有才能看见
                     //   "/swagger-ui.html"       // swagger页面
                        "/error"                 // Spring Boot错误处理端点
                );

2. 通过Java配置类配置

你也可以通过创建配置类来定义OpenAPI的基本信息。Knife4j会自动配置SpringDoc，所以你通常不需要额外的启用注解。

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
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;

@Configuration
public class Knife4jConfig { // 或 SwaggerConfig

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("default") // 分组名称
                .pathsToMatch("/**") // 接口路径匹配规则
//                .packagesToScan("com.yourpackage.controller") // 也可在此指定扫描包
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("你的API标题")
                        .description("你的API描述信息")
                        .version("1.0")
                        .contact(new Contact().name("联系人").email("contact@example.com")) // 联系方式
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))); // 许可证信息
    }
}

说明：通过GroupedOpenApiBean可以创建不同的API分组，适用于模块化项目。

📝 使用注解描述API

在Controller和接口方法上使用OpenAPI 3（也称为SpringDoc）注解来描述API。

常用注解对照（与旧版Swagger 2注解不同）：

  • @Api → @Tag
  • @ApiOperation → @Operation
  • @ApiParam → @Parameter
  • @ApiModel → @Schema
  • @ApiModelProperty → @Schema

应用示例：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Tag(name = "用户接口", description = "用户相关的API") // 类级别，描述模块
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户详情", description = "根据用户ID获取用户的详细信息") // 方法级别，描述接口
    public User getUser(@Parameter(description = "用户ID", required = true) @PathVariable Long id) { // 参数级别，描述参数
        // ... 业务逻辑
    }

    @PostMapping
    @Operation(summary = "创建用户")
    public User createUser(@RequestBody User user) {
        // ... 业务逻辑
    }
}

实体类示例：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户实体") // 描述模型
public class User {
    
    @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED)
    private String username;
    
    @Schema(description = "邮箱")
    private String email;
    
    // 省略getter/setter
}

🌐 访问与查看文档

完成配置并启动应用后，你可以通过以下地址访问API文档：

  • Knife4j增强文档界面：http://localhost:8080/doc.html
  • 原生Swagger界面：http://localhost:8080/swagger-ui.html

Knife4j的增强界面 (doc.html) 提供了更丰富的功能和更友好的UI。

🛠️ 进阶配置技巧

1. 全局添加自定义请求参数

若需为所有接口全局添加一个自定义请求头（如鉴权Token），可以配置一个GlobalOpenApiCustomizer Bean。

import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Optional;

@Configuration
public class GlobalHeaderConfig {

    @Bean
    public GlobalOpenApiCustomizer globalHeaderCustomizer() {
        return openApi -> {
            // 创建自定义请求头参数
            HeaderParameter authHeader = new HeaderParameter();
            authHeader.setName("Authorization"); // 头字段名
            authHeader.setRequired(false); // 是否必填
            authHeader.setSchema(new StringSchema()); // 参数类型

            // 遍历所有接口，为每个操作添加该请求头
            openApi.getPaths().values().forEach(pathItem ->
                pathItem.readOperations().forEach(operation ->
                    operation.addParametersItem(authHeader)
                )
            );
        };
    }
}

2. 安全认证配置

可以在application.yml中配置基础的HTTP认证，保护你的API文档。

knife4j:
  enable: true
  basic:
    enable: true  # 开启Basic认证
    username: admin  # 自定义用户名
    password: 123456  # 自定义密码

3. 生产环境屏蔽

建议在生产环境中关闭API文档，或通过配置确保其不会对外暴露。

knife4j:
  production: true  # 开启生产环境屏蔽，将禁用API文档的访问

⚠️ 常见问题排查

  • 依赖冲突：Knife4j的Starter已经包含了springdoc-openapi的依赖，请确保项目中未重复引入其他Swagger或SpringDoc依赖，以避免冲突。
  • 注解不生效：
    • 检查packages-to-scan配置的包路径是否正确。
    • 确认使用的是OpenAPI 3的注解（如@Tag, @Operation），而非Swagger 2的旧注解（如@Api, @ApiOperation）。
  • 页面无法访问/404：
    • 确认依赖已正确引入。
    • 检查Knife4j增强是否已启用 (knife4j.enable: true) 。
    • 确保项目是一个Web应用（例如引入了spring-boot-starter-web）。

💎 核心要点回顾

在Spring Boot 3中集成Knife4j，关键在于：

  1. 使用正确的依赖：knife4j-openapi3-jakarta-spring-boot-starter。
  2. 配置SpringDoc的扫描路径 (packages-to-scan)。
  3. 开启Knife4j增强功能 (knife4j.enable: true)。
  4. 使用OpenAPI 3的新注解 (@Tag, @Operation, @Schema等) 来描述API。

希望这份详细的指南能帮助你在Spring Boot 3项目中顺利集成和使用Knife4j！如果你在整合过程中遇到更具体的问题，比如特定注解的用法或者更复杂的配置场景，我很乐意提供进一步的帮助。

在Springboot2中使用

在 Spring Boot 2.x 项目中集成 Knife4j 确实是个提高 API 文档管理和协作效率的好方法。下面我为你梳理其核心配置步骤、注解使用及一些实用技巧。

📦 添加项目依赖

在 pom.xml 中引入 Knife4j 依赖。根据 Spring Boot 2.x 版本，常用的 Starter 有：

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

或者使用 OpenAPI 2 规范的 Starter：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

说明：Knife4j 的 Starter 通常已经包含了 Swagger 2 的相关依赖，所以你一般不需要再单独引入 springfox-swagger2。

⚙️ 核心配置详解

1. 配置 Docket Bean

Docket 是 Swagger 2 的核心配置类，用于配置 API 文档的生成规则。创建一个配置类（例如 SwaggerConfig 或 Knife4jConfiguration）：

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 启用 Swagger2
@EnableKnife4j  // 启用 Knife4j 增强功能
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 指定文档信息
                .apiInfo(apiInfo())
                // 选择生成哪些接口文档
                .select()
                // 配置要扫描的控制器包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                // 配置路径过滤
                .paths(PathSelectors.any())
                .build()
                // 分组支持
                .groupName("默认接口");
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 接口文档")
                .description("这是一个基于 Spring Boot 的 RESTful API 文档")
                .termsOfServiceUrl("http://example.com")
                .contact(new Contact("开发者", "http://example.com", "contact@example.com"))
                .version("1.0")
                .build();
    }
    
    // 可以配置多个 Docket Bean 实现接口分组
    @Bean
    public Docket adminApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理员接口")
                .apiInfo(adminApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.admin.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("管理员接口文档")
                .description("系统管理员专用接口")
                .version("1.0")
                .build();
    }
}

配置说明：

  • @EnableSwagger2 与 @EnableKnife4j：这两个注解通常需要同时使用，@EnableSwagger2 启用 Swagger 2，@EnableKnife4j 启用 Knife4j 的增强功能。
  • 包扫描路径：通过 RequestHandlerSelectors.basePackage 指定你的 Controller 所在包，Swagger 会扫描该包下的接口。
  • 接口分组：配置多个 Docket Bean 可实现接口分组管理，适用于模块化项目。

2. 静态资源映射

在 Spring Boot 2.x 中，手动配置静态资源映射通常是必要的，否则可能访问 doc.html 时出现 404 错误。

实现 WebMvcConfigurer 接口并重写 addResourceHandlers 方法：

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

说明：这些静态资源映射确保了 Knife4j 的前端页面（doc.html）及其相关 CSS、JS 文件能够被正确访问。

3. 拦截器放行

如果项目中有登录拦截器，需要将 Knife4j 相关的资源路径排除，否则文档页面可能无法访问：

// 在拦截器配置中，添加不需要处理的请求路径
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new LoginCheckFilter())
            .addPathPatterns("/**")
            .excludePathPatterns(
                "/doc.html",
                "/webjars/**",
                "/swagger-resources",
                "/v2/api-docs"
            );
}

4. 解决路径匹配冲突

在 Spring Boot 2.6及以上版本，可能会遇到与 Swagger 的路径匹配冲突，启动时报 Failed to start bean 'documentationPluginsBootstrapper' 错误。在 application.yml 中添加：

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

📝 使用 Swagger 注解描述 API

在 Controller 和实体类上使用 Swagger 2 注解来描述 API，这些注解是生成文档的关键。

Controller 层注解示例

import com.example.model.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理接口") // 描述Controller类，tags用于分组
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详情", notes = "根据用户ID获取用户的详细信息") // 描述接口方法
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path") // 描述单个参数
    @ApiResponses({
        @ApiResponse(code = 200, message = "成功", response = User.class),
        @ApiResponse(code = 404, message = "用户不存在")
    }) // 描述响应状态码
    public User getUser(@PathVariable Long id) {
        // 业务逻辑
        return new User();
    }

    @PostMapping
    @ApiOperation(value = "创建用户", notes = "创建新用户")
    public User createUser(@RequestBody @ApiParam(value = "用户信息", required = true) User user) { // 描述复杂对象参数
        // 业务逻辑
        return user;
    }

    @GetMapping("/list")
    @ApiOperation(value = "获取用户列表", notes = "支持分页查询用户列表")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "页码", defaultValue = "1", dataType = "int", paramType = "query"),
        @ApiImplicitParam(name = "size", value = "每页大小", defaultValue = "10", dataType = "int", paramType = "query")
    }) // 描述多个参数
    public List<User> getUserList(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") int size) {
        // 业务逻辑
        return List.of();
    }
}

实体类注解示例

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(description = "用户实体") // 描述实体类
public class User {
    
    @ApiModelProperty(value = "用户ID", example = "1") // 描述实体类属性
    private Long id;
    
    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan")
    private String username;
    
    @ApiModelProperty(value = "邮箱", example = "user@example.com")
    private String email;
    
    // 省略 getter 和 setter 方法
}

常用注解总结：

注解位置说明
@Api类加在Controller类上，表示对类的说明，tags属性用于接口分组。
@ApiOperation方法说明方法的用途、作用。
@ApiImplicitParam方法描述单个请求参数。
@ApiImplicitParams方法包含多个@ApiImplicitParam。
@ApiParam参数描述单个参数，通常用于描述复杂对象或个别参数详情。
@ApiModel实体类描述实体类。
@ApiModelProperty实体类属性描述实体类的属性。
@ApiResponse方法描述一个HTTP响应。
@ApiResponses方法描述多个HTTP响应。

🌐 访问文档界面

完成配置并启动应用后，可以通过以下地址访问文档：

  • Knife4j 增强文档：http://localhost:8080/doc.html
  • 原生 Swagger 文档：http://localhost:8080/swagger-ui.html

Knife4j 的增强界面 (doc.html) 提供了更丰富的功能和更友好的 UI。

🛠️ 高级功能与配置

1. 接口分组管理

对于大型项目，可以使用多个 Docket 进行接口分组，使文档结构更清晰：

@Bean
public Docket defaultApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("默认接口")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(PathSelectors.any())
            .build();
}

@Bean
public Docket adminApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("管理员接口")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.admin.controller"))
            .paths(PathSelectors.ant("/admin/**"))
            .build();
}

2. 安全认证配置

为文档界面添加基础认证，保护 API 文档：

# 在 application.yml 中配置
knife4j:
  basic:
    enable: true
    username: admin
    password: 123456

3. 生产环境屏蔽

生产环境建议关闭 API 文档，或通过配置确保其不会对外暴露：

knife4j:
  production: true  # 开启生产环境屏蔽，将禁用 Knife4j 相关功能

或者使用 @Profile 注解限定配置类只在特定环境生效：

@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({"dev", "test"}) // 只在开发和测试环境生效
public class SwaggerConfig {
    // 配置内容...
}

⚠️ 常见问题排查

  1. 启动报错（如Failed to start bean 'documentationPluginsBootstrapper'）：

    • 在 Spring Boot 2.6+ 版本，检查是否已配置 spring.mvc.pathmatch.matching-strategy=ant_path_matcher。
    • 也可尝试在启动类添加 @EnableWebMvc。

  2. 访问文档地址报 404：

    • 检查依赖是否正确引入。
    • 确认静态资源映射已配置（doc.html 和 /webjars/**）。
    • 验证配置类注解（@EnableSwagger2, @EnableKnife4j）是否添加。
    • 检查拦截器是否放行了 Knife4j 相关路径。

  3. 依赖冲突：

    • 注意避免重复引入 Swagger 或 Knife4j 的不同版本依赖，以免引起版本冲突。通常只引入 Knife4j Starter 即可。

💎 核心要点回顾

在 Spring Boot 2.x 中集成 Knife4j，关键在于：

  1. 引入正确的 Knife4j Starter 依赖。
  2. 配置 Docket Bean，指定文档信息和扫描路径。
  3. 手动配置静态资源映射（特别是在 Spring Boot 2.6+ 版本）。
  4. 使用 Swagger 2 注解（如 @Api, @ApiOperation, @ApiModelProperty 等）描述 API。
  5. 根据需要，进行接口分组、安全认证等高级配置。

希望这份详细的指南能帮助你在 Spring Boot 2.x 项目中顺利集成和使用 Knife4j。如果你在整合过程中遇到更具体的问题，比如特定注解的用法或者更复杂的配置场景，我很乐意提供进一步的帮助。

默认页脚
Copyright © 2025 JustQ