在 Spring Boot 中使用 Knife4j 生成接口文档

前言

Knife4j 是一个基于 Swagger 的增强 UI 实现，主要用于为 Spring Boot 应用程序生成 API 接口文档。它不仅支持标准的 OpenAPI 规范，还提供了更加友好的界面和强大的功能。本文将详细介绍如何在 Spring Boot 中集成 Knife4j，并通过不同注解来生成清晰的接口文档。同时，我们也会比较 Spring Boot 2.x 和 Spring Boot 3.x 版本中使用 Knife4j 的差异。

一、Knife4j 简介

Knife4j 是 Swagger 的增强工具包，其核心特性包括：

• 支持 OpenAPI 2.0 / 3.0
• 提供更美观的 UI 界面
• 支持接口调试
• 支持分组管理
• 支持离线文档导出（HTML/PDF）

二、Spring Boot 集成 Knife4j

1. 添加依赖

Spring Boot 2.x（基于 Swagger 2）

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

Spring Boot 3.x（基于 Swagger 3/OpenAPI 3.0）

从 Spring Boot 3.x 开始，官方全面转向 Jakarta EE 9+，包名由 javax 变更为 jakarta，因此需要使用适配 Jakarta 的版本。

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

注意：Spring Boot 3.x 使用的是 OpenAPI 3.0，而不再是 Swagger 2。

2. 启用 Knife4j

创建配置类或直接在主启动类上添加注解启用 Knife4j。

Spring Boot 2.x

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfig {
}

Spring Boot 3.x

import com.github.xiaoymin.knife4j.core.constants.Knife4jOpenApi3UrlConstant;
import com.github.xiaoymin.knife4j.openap3.configuration.OpenApi3Configuration;
import com.github.xiaoymin.knife4j.spring.boot.extension.OpenApi3ExtensionResolver;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Spring Boot 3.x Knife4j 示例")
                        .version("1.0")
                        .description("基于 OpenAPI 3.0 的接口文档"));
    }

    // 必须加上这个 Bean 才能启用 Knife4j 的扩展功能
    @Bean
    public OpenApi3ExtensionResolver openApi3ExtensionResolver() {
        return new OpenApi3ExtensionResolver();
    }
}

三、常用注解说明

1. 控制器级别注解

示例：

@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
}

2. 方法级别注解

示例：

Spring Boot 2.x

@GetMapping("/list")
@ApiOperation(value = "获取用户列表", notes = "返回所有用户信息")
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNum", value = "页码", required = true, dataType = "int"),
    @ApiImplicitParam(name = "pageSize", value = "每页数量", required = false, dataType = "int")
})
public List<User> listUsers(int pageNum, int pageSize) {
    return userService.list(pageNum, pageSize);
}

Spring Boot 3.x

@GetMapping("/list")
@Operation(summary = "获取用户列表", description = "返回所有用户信息")
@Parameters({
    @Parameter(name = "pageNum", description = "页码", required = true),
    @Parameter(name = "pageSize", description = "每页数量", required = false)
})
public List<User> listUsers(int pageNum, int pageSize) {
    return userService.list(pageNum, pageSize);
}

3. 参数对象字段注解

当使用实体类接收参数时，可以对字段进行描述。

示例：

public class UserDTO {
    @Schema(description = "用户名", example = "admin")
    private String username;

    @Schema(description = "密码", example = "123456")
    private String password;
}

四、访问 Knife4j 文档页面

启动项目后，访问以下地址查看接口文档：

• Spring Boot 2.x：

  http://localhost:8080/knife4j-ui.html
  

• Spring Boot 3.x：

  http://localhost:8080/doc.html
  

五、常见问题与注意事项

1. Spring Boot 3.x 下无法访问 /doc.html

请确保你使用了正确的 Starter 包（带 openapi3-jakarta 字样），并且正确配置了 OpenAPI Bean。

2. 参数没有显示注释

确保你在实体类字段上使用了 @Schema 或 @ApiModelProperty 注解，并且开启了相应的自动扫描。

3. 多个接口分组展示

可以通过 Docket（Spring Boot 2.x）或 OpenAPI + 分组配置（Spring Boot 3.x）实现多组接口文档。

六、总结

七、参考资料

• Knife4j GitHub
• SpringDoc OpenAPI
• OpenAPI 3.0 Specification