Knife4j Next

Appearance

快速开始 ​

本指南给出四条接入路径对应的最小可运行工程。每条路径都经过 master 的 knife4j-smoke-tests 模块回归验证。

先决定走哪条路径

  • 已经升级 Spring Boot 4.x：用 OpenAPI3 Boot4 starter，UI 是新 React 版本。
  • 新项目、Spring Boot 3.x、不想踩 javax/jakarta 雷：用 OpenAPI3 Jakarta，UI 是新 React 版本。
  • 还在 Spring Boot 2.7.x：可以继续用 OpenAPI2（Springfox），UI 是本仓库 front/vue3 构建产物（兼容维护）；或 OpenAPI3（springdoc-openapi 非 Jakarta），UI 是 React 新前端。
  • 已经在 upstream knife4j：先看 迁移指引，只改 groupId 即可，不必换路径。

如果不确定哪个版本合适，先看 版本参考表。

路径一：Spring Boot 4.x + OpenAPI3 Boot4（默认推荐） ​

环境要求 ​

待发布源码升级

当前源码的 Boot3 Jakarta WebMVC、WebFlux 与独立聚合使用 springdoc 2.9.1，Swagger Jakarta annotations / models / core 统一为 2.2.55。JDK 下限仍为 17；Boot 3.4 线下限为 3.4.7，Boot 3.5 线下限为 3.5.1（共同需要 Framework 6.2.8）。Boot 3.5.0 不满足此下限。 这是待发布源码的要求；下方 5.7.7 及更早版本的历史依赖与兼容记录保持原样。 详见版本对照。

  • JDK 17+
  • Spring Boot 4.0.x（smoke-tests 覆盖 4.0.8）
  • springdoc-openapi 3.0.3（starter 已管理，无需显式声明）

依赖 ​

xml
<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-boot4-spring-boot-starter</artifactId>
    <version>5.7.7</version>
</dependency>

最小 application.yml ​

yaml
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.example.demo

knife4j:
  enable: true
  setting:
    language: zh_cn

Controller 写法与 Boot 3.x Jakarta 版一致，annotation 使用 io.swagger.v3.oas.annotations。

验证 ​

  1. mvn spring-boot:run。
  2. 浏览器打开 http://localhost:8080/doc.html，应看到 React 版界面。
  3. http://localhost:8080/v3/api-docs 返回原始 OpenAPI JSON。
  4. http://localhost:8080/knife4j/config 返回 Knife4j UI 内部运行时配置；该接口不会出现在 doc.html 接口列表中。

路径二：Spring Boot 3.x + OpenAPI3 Jakarta ​

环境要求 ​

  • JDK 17+
  • Spring Boot 3.4.0 ~ 3.5.x（smoke-tests 覆盖 3.4.5、3.5.0，以及 Gateway Server Web MVC 的 3.5.16）
  • springdoc-openapi-jakarta 2.8.9（starter 已管理，无需显式声明）

依赖 ​

xml
<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>5.7.7</version>
</dependency>

最小 application.yml ​

yaml
knife4j:
  enable: true

springdoc 默认暴露 /v3/api-docs 与 /swagger-ui.html，Knife4j 默认语言是 zh_cn。 如果你的 Controller 不在启动类包及其子包下，或希望限制文档范围，再补充：

yaml
springdoc:
  packages-to-scan: com.example.demo
  paths-to-match: /api/**
  swagger-ui:
    tags-sorter: alpha
    operations-sorter: alpha

示例 Controller ​

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

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @Operation(summary = "按 id 查询用户")
    @GetMapping("/{id}")
    public UserDto get(@PathVariable Long id) {
        return new UserDto(id, "alice");
    }

    @Operation(summary = "新增用户")
    @PostMapping
    public UserDto create(@RequestBody UserDto body) {
        return body;
    }
}

验证 ​

  1. mvn spring-boot:run 或运行 knife4j-demo-openapi3 模块。
  2. 浏览器打开 http://localhost:8080/doc.html，应看到 React 版界面。
  3. http://localhost:8080/v3/api-docs 返回原始 OpenAPI JSON。

新前端配置覆盖范围

React 新前端会读取部分 knife4j.setting.* UI 默认值，例如 language、enable-debug、enable-search、enable-open-api、enable-host、enable-group、enable-footer、enable-footer-custom、footer-custom-content、enable-request-cache、enable-version、enable-home-custom、home-custom-location、swagger-model-name。enable-version 已接通，UX 是 NEW / 变化标记，不同于 Vue2 小蓝点。仍缺 afterScript 与调试后刷新变量（enable-reload-cache-parameter）。home-custom-path 仍只由后端读取并注入 Markdown 内容。详见 FAQ / 为什么我的 knife4j.setting 配置不生效 与 相对 Vue2 的覆盖范围。

路径三：Spring Boot 2.x + OpenAPI3（springdoc-openapi） ​

环境要求 ​

  • JDK 8 / 11 / 17
  • Spring Boot 2.4.0 ~ 2.7.x（建议 2.7.18）
  • springdoc-openapi 1.8.0（starter 已管理）

依赖 ​

xml
<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>5.7.7</version>
</dependency>

最小 application.yml ​

yaml
knife4j:
  enable: true

springdoc 默认路径已经是 /v3/api-docs 与 /swagger-ui.html，中文界面也是 Knife4j 默认值。 如需限制扫描范围，可追加 springdoc.packages-to-scan、springdoc.paths-to-match 或 springdoc.group-configs。

Controller 写法与 Jakarta 版一致，annotation 使用 io.swagger.v3.oas.annotations。

UI 同样是新 React 版本，注意覆盖范围提示。

路径四：Spring Boot 2.x + OpenAPI2（Springfox，Vue 3 UI） ​

何时选这条

  • 项目深度依赖 Springfox 专属注解（@ApiOperationSupport(ignoreParameters/includeParameters)、@DynamicParameters、@DynamicResponseParameters）。
  • 需要 Vue2 基线里的 afterScript 或调试后刷新变量（enable-reload-cache-parameter）。这两项已移植到本仓库 front/vue3，React 尚未覆盖。
  • 自定义首页、接口变化提示和 OpenAPI 复制/下载不是选这条的理由：React 已覆盖（变化提示是 NEW / 变化标记，不是 Vue2 小蓝点）。三端都没有独立的 Postman Collection 导出器。

依赖 ​

xml
<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>5.7.7</version>
</dependency>

最小 application.yml ​

yaml
knife4j:
  enable: true
  openapi:
    title: Knife4j 示例
    description: "`我是测试`"
    email: you@example.com
    concat: maintainer
    version: v1.0
    license: Apache 2.0
    group:
      default:
        group-name: 默认分组
        api-rule: package
        api-rule-resources:
          - com.example.demo

示例 Controller（Swagger 2 annotations） ​

java
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;

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

    @ApiOperation("按 id 查询用户")
    @GetMapping("/{id}")
    public UserDto get(@ApiParam("用户 id") @PathVariable Long id) {
        return new UserDto(id, "alice");
    }
}

可选：启用 Docket 扩展体系 ​

java
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean
    public Docket defaultApi() {
        String group = "默认分组";
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName(group)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .extensions(openApiExtensionResolver.buildExtensions(group));
    }
}

跑不起来？ ​

  1. doc.html 返回 404：确认 starter 在 classpath 里，且 knife4j.enable=true。若 context-path 非根，访问 http://localhost:8080/<context-path>/doc.html。
  2. 看到 Swagger 原生 UI 而不是 Knife4j 界面：通常是引入了 springfox-boot-starter 或 springdoc-openapi-ui 的非 jakarta 版本与 jakarta starter 冲突。
  3. No OpenAPI resource found for group: swagger-config：参考 FAQ。
  4. 生产环境想隐藏 doc.html：设置 knife4j.production=true，并视需要启用 knife4j.basic。

更多问题见 FAQ。

下一步 ​

让 OpenAPI 文档更清晰，让接口联调更顺手。

Apache-2.0 · Knife4j Next