Knife4j is an enhanced API documentation tool built on top of Swagger for Java MVC applications. It evolved from the swagger-bootstrap-ui project and aims to be a compact yet powerful utility, offering a polished user interface and integrated debugging capabilities.

Two pivotal features define its utility:

• Auto-generated documentation: Following the OpenAPI specification, it renders detailed interface descriptions including endpoint paths, HTTP methods, request/response samples, parameters, and status codes.
• Live API testing: Developers can send requests directly from the documentation UI, inspect response headers, timing, and returned data without external tools.

Key advantages include OpenAPI 2.0/3.0 compatibility, UI extensions (custom docs, i18n, sorting), automtaic starter for Springdoc-openapi + OAS3, unified aggregation for API gateways, and cloud-native solutions for Kubernetes and Docker.

Integrating Knife4j in a Spring Boot 3.2 Project

Below is a step-by-step setup using a sample project named staff-service.

1. Add the Starter

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

2. Application Configuration

Configure both Srpingdoc and Knife4j in application.yml:

springdoc:
  swagger-ui:
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
    enabled: true
  group-configs:
    - group: 'Staff Service APIs'
      paths-to-match: '/**'
      packages-to-scan: com.company.staff
knife4j:
  enable: true
  setting:
    language: en
    swagger-model-name: 'Entity Models'

3. Enable Knife4j

Annotate the main application class:

@EnableKnife4j
@SpringBootApplication
public class StaffApplication {
    public static void main(String[] args) {
        SpringApplication.run(StaffApplication.class, args);
    }
}

4. OpenAPI Metadata

Create a configuration bean to provide API metadata:

@Configuration
public class ApiDocsConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Staff Management API")
                        .version("2.0")
                        .description("Internal documentation - disable in production")
                        .contact(new Contact()
                                .name("Jane Doe")
                                .url("https://example.com")
                                .email("jane.doe@example.com")));
    }
}

5. Annotate REST Controllers

Use Swagger/OpenAPI annotations on endpoint methods and DTOs:

@Tag(name = "Employee Management")
@RestController
@RequestMapping("/api/employees")
public class EmployeeController {

    @Autowired
    private EmployeeService employeeService;

    @Operation(summary = "Paginated employee list")
    @PostMapping("/search")
    public ResponseEntity<PageResult<EmployeeVO>> search(@RequestBody @Valid EmployeeQuery query) {
        return ResponseEntity.ok(employeeService.searchByPage(query));
    }

    @Operation(summary = "Create employee")
    @PostMapping
    public ResponseEntity<String> create(@RequestBody @Valid EmployeeCreateCmd cmd) {
        return ResponseEntity.ok(employeeService.create(cmd));
    }

    @Operation(summary = "Delete by ID")
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@Parameter(description = "Employee ID") @PathVariable @NotBlank String id) {
        employeeService.removeById(id);
        return ResponseEntity.noContent().build();
    }
}

Corresponding DTO example:

@Data
@Schema(description = "Employee search payload")
public class EmployeeQuery extends PageRequest {

    @Schema(description = "Full name")
    private String fullName;

    @Schema(description = "Department code")
    private String deptCode;

    @Schema(description = "Email address")
    private String email;
}

6. Launch and Explore

After starting the application, the documentation UI is available at:

http://localhost:8080/doc.html

The page renders API groups, detailed parameter descriptions, and an interactive console for sending requests and viewing raw responses.