1. Project Overview

Knife4j is an enhanced solution that integrates Swagger2 and OpenAPI3.

It helps developers quickly aggregate and use the OpenAPI specification.

Knife4j is an enhanced solution for integrating Swagger to generate API documentation in Java MVC frameworks. Formerly known as swagger-bootstrap-ui, the name Knife4j reflects the hope that it will be as compact and lightweight as a dagger while remaining powerful in functionality!

Knife4j was formerly known as swagger-bootstrap-ui. To better align with the development of microservice architectures, the project was officially renamed Knife4j. The original swagger-bootstrap-ui used a mixed packaging approach combining backend Java code and frontend UI, which made it cumbersome in microservice architectures.

Main areas of focus after the renaming:

• Separates backend and frontend Java code from the frontend UI module, making it more flexible to use in microservice architectures.
• Provides enhanced solutions focused on Swagger, rather than simply improving and enhancing the frontend UI.
• Provides more flexible middleware solutions and tools.

2. Open Source License

Licensed under Apache-2.0

3. Screenshots

4. Feature Overview

Core Features

• Compatible with OpenAPI 2.0
• Compatible with OpenAPI 3.0

Enhanced Extensions

• Basic UI components (custom documentation, dynamic parameter debugging, I18n, API sorting, export, etc.)
• Automatic injection starter based on the Springfox framework and Swagger2 specification
• Automatic injection starter based on Springdoc-openapi and the OAS3 specification
• Provides a unified solution for aggregating OpenAPI API documentation across mainstream gateway components.

Framework Compatibility

• Compatible with Spring MVC
• Compatible with Spring Boot 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, and 3.0
• Compatible with Spring WebFlux
• Provides enhanced extensions for the Swagger2 specification based on SpringFox 2.x
• Provides enhanced extensions for the OAS3 specification based on the Springdoc-openapi project

Community Ecosystem

• Microservice aggregation middleware Knife4jAggregation based on the Servlet ecosystem
• Microservice aggregation middleware based on Spring Cloud Gateway
• Standalone middleware Knife4jDesktop

Project Modules

The main modules in the current repository are described below:

Module Name

Description

knife4j

An enhanced solution for integrating Swagger into Java MVC frameworks, with middleware encapsulation for the Java ecosystem.

knife4j-insight

A ready-to-use standalone solution with official Docker images, built on Spring Boot 3.0. See the usage documentation.

knife4j-doc

Official Knife4j documentation, built with Docusaurus. Refer to the documentation for contribution guidelines.

knife4j-vue

Current Knife4j frontend source code, built with Vue2.0.

knife4j-vue3

Current Knife4j frontend source code, built with Vue3.0. This codebase was contributed by a community member and is not yet in use.

knife4j-front

Knife4j frontend architecture code. Currently in the planning stage, this module has not yet been implemented. If you have any ideas, you can contact the author through the discussion group.

5. Tech Stack

Quick Start (Spring Boot 2 + OpenAPI2)

For usage with other specifications and Spring Boot 3 with OpenAPI3, please refer to the detailed documentation.

Step 1: Create a Spring Boot project and add the Knife4j dependency to pom.xml, as shown below:

<!-- Import the official Knife4j starter package. This guide uses Spring Boot version <3.0. Developers should take note. -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

Step 2: Create the Swagger configuration dependency, as shown below:

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //Specify the use of the Swagger2 specification
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                //The description field supports Markdown syntax
                .description("# Knife4j RESTful APIs")
                .termsOfServiceUrl("[https://doc.xiaominfo.com/\](https://doc.xiaominfo.com/\)")
                .contact("xiaoymin@foxmail.com")
                .version("1.0")
                .build())
                //Group name
                .groupName("User Service")
                .select()
                //Specify the Controller package path to scan here
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

Step 3: Create a new API Controller class, as shown below:

@Api(tags = "Home Module")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "Name",required = true)
    @ApiOperation(value = "Greet the Guest")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}

Everything is ready. Start the Spring Boot project and visit the Knife4j documentation URL in your browser to view the results.

http://localhost:8080/doc.html