Integrating Knife4j with OpenAPI 3 in Spring Boot 3.x – Step‑by‑Step Guide

1. Add Maven Dependencies

For Spring Boot 3.x, include the SpringDoc core starter and the Knife4j OpenAPI3 starter in pom.xml:

<dependencies>
  <!-- SpringDoc OpenAPI 3 core -->
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
  </dependency>

  <!-- Knife4j OpenAPI 3 -->
  <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
  </dependency>
</dependencies>

Note: springdoc-openapi-starter-webmvc-ui provides basic OpenAPI 3 support, while knife4j-openapi3-jakarta-spring-boot-starter adds the enhanced UI and must match the Jakarta‑based Spring Boot 3.x runtime.

2. Configuration File (application.yml)

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.controller
knife4j:
  enable: true
  setting:
    language: zh_cn

3. API Documentation Configuration Class

package com.example.demo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
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("示例项目 API 文档")
                .version("1.0")
                .description("这是使用 Knife4j + OpenAPI3 生成的接口文档示例")
                .contact(new Contact().name("Test").email("[email protected]"))
                .license(new License().name("Apache 2.0").url("http://springdoc.org")));
    }
}

4. Sample Controller

package com.example.demo.controller;

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

@Tag(name = "用户管理", description = "用户的增删改查接口")
@RestController
@RequestMapping("/user")
public class UserController {
    @Operation(summary = "获取用户信息", description = "根据用户ID获取信息")
    @GetMapping("/{id}")
    public String getUser(@PathVariable Long id) {
        return "User ID: " + id;
    }

    @Operation(summary = "新增用户", description = "创建一个新用户")
    @PostMapping
    public String addUser(@RequestParam String name) {
        return "创建用户: " + name;
    }
}

5. Run the Application & Access URLs

Knife4j UI (enhanced): http://localhost:8080/doc.html Swagger UI (native): http://localhost:8080/swagger-ui.html OpenAPI JSON:

http://localhost:8080/v3/api-docs

6. Common Issues & Solutions

Blank page or 404: Ensure knife4j.enable=true and the path /doc.html is correct.

API not displayed: Verify that springdoc.group-configs.packages-to-scan includes the package containing your controllers.

Using Spring Boot 2.x: Replace the starter with knife4j-spring-boot-starter + springfox or springdoc-openapi-ui (the latter is no longer fully maintained).

7. Comparison Between SpringDoc OpenAPI and Knife4j OpenAPI3

Core Functionality: SpringDoc implements the OpenAPI 3 specification and generates API metadata; Knife4j builds on SpringDoc and provides an enhanced UI.

UI Experience: SpringDoc offers the basic Swagger UI; Knife4j adds search, export, debugging, and full Chinese localization.

Offline Documentation: Knife4j supports Markdown/HTML/Word export, while SpringDoc does not.

Security Controls: Knife4j provides richer security configuration options.

Production Support: Knife4j can disable documentation with a single flag; SpringDoc requires manual disabling.

Micro‑service Support: Knife4j includes gateway aggregation features; SpringDoc requires custom implementation.

8. Recommendation Scenarios

Choose SpringDoc OpenAPI when the project needs strict OpenAPI 3 compliance, the team prefers English documentation, and UI customization is minimal.

Choose Knife4j OpenAPI3 for Chinese teams that require a richer UI, offline export, micro‑service gateway aggregation, and advanced security settings.

Both can be used together: SpringDoc generates the OpenAPI JSON, while Knife4j renders the enhanced UI.

9. Best‑Practice Tips

Version selection: Spring Boot 2.x → SpringDoc 1.x + Knife4j 4.x; Spring Boot 3.x → SpringDoc 2.x + Knife4j 4.3.0+.

Code organization: Keep OpenAPI configuration in a dedicated config package and use @Tag to group APIs.

Model documentation: Annotate fields with @Schema for detailed property descriptions.

Documentation maintenance: Use @Operation with clear summary and description values; protect sensitive endpoints with security annotations.

Team collaboration: Export documentation via Knife4j’s offline feature and share with tools like Apifox.

Conclusion

SpringDoc OpenAPI and Knife4j OpenAPI3 each have distinct strengths; the optimal choice depends on project requirements. For Chinese‑focused teams or projects needing advanced UI features, Knife4j is usually the better fit, while SpringDoc suits teams emphasizing standard compliance and internationalization. The two solutions are complementary and can be combined for maximum flexibility.