Bye, Swagger UI! Chinese people open source a super easy-to-use API document generation framework, Star 4.7K +, really fragrant!!


Recently, the stack leader found that some domestic open source projects use Knife4j technology, which is very sharp according to the name!

Is it such an abbreviation:

Knife4j = Knife for Java ?

Java dagger?

It looks awesome. Of course, this is my simple guess. I can't literally guess what it is used for!

So what kind of framework is it?

Introduction to Knife4j

Knife4j's predecessor is Swagger bootstrap UI. In fact, it is a skin project of pure Swagger UI. Those who have used Swagger should know that Swagger UI is not easy to use and is not suitable for Chinese people. Therefore, Swagger bootstrap UI project was born.

In order to meet many personalized needs, swagger bootstrap UI adds many rich server-side features. It no longer only focuses on the front-end UI skin, so it is renamed knife4j.

Named knife4j, it is hoped that it can be as small, lightweight and powerful as a dagger. It is also hoped that it can become a universal and enhanced solution for Swagger interface document service.

Knife4j was opened by Xiao Ming, a Chinese programmer, in 2017. It has been more than 4 years now. The number of stars has exceeded 4.7k +:

Knife4j also won the title of GVP project, that is, Gitee's most valuable open source project. I found that more and more open source projects are using it now, and the Swagger UI can be thrown away..

Official website address:

Open source address:

Knife4j interface appreciation

Knife4j adopts Vue + And Design Vue components for rewriting, and relevant interfaces are brought out for your appreciation.

Interface document display interface:

Interface debugging interface:

Swagger Models features:

Supports exporting offline Markdown and Html:

knife4j is indeed very powerful. The whole interface is based on the left and right menu layout. It supports multiple labels to open, display and switch at the same time. The documents and debugging are clearer. It feels more in line with the operating habits of Chinese people..

Knife4j actual combat

knife4j currently mainly supports Java development, and supports the integrated use of Spring MVC, Spring Boot and Spring Cloud framework.

The stack leader of this article is based on Spring Boot, and the actual combat is as follows:

  • Spring Boot 2.5.0
  • Knife4j 2.0.9
  • Maven 3.6.3
  • JDK 1.8

Note: using knife4j version 2.0.6 +, the Spring Boot version requires 2.2.x+

1. Knife4j dependency introduction


2. Knife4j configuration

Enable enhanced features and basic login authentication:

  # Turn on enhancement
  enable: true
  # Turn on login authentication
    enable: true
    username: test
    password: test

Support personalized configuration items, such as interface address, interface description attribute, UI enhancement and other personalized configuration functions:

 * Knife4j Configuration class
 * WeChat official account: Java technology stack
 * Author: stack length
public class Knife4jConfiguration {

    @Bean(value = "defaultDocket")
    public Docket defaultDocket() {
        // contact information 
        Contact contact = new Contact("Official account: Java Technology stack", "", "");

        // Create Docket
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("Knife4j test")
                        .description("Knife4j Test")
        return docket;


I won't introduce the basics of Spring Boot. I'll give you a copy< Spring Boot learning notes "HD theory + real war version", according to the study, no, the latest version is working hard to update, and can continue to pay attention to the official account Java technology stack, will be the first time to share with you.

3. Add test interface

Add two test interfaces, one login (POST) and one say hello (GET).

 * Knife4j Test interface
 * WeChat official account: Java technology stack
 * Author: stack length
@Api(tags = "Test module")
public class Knife4jController {

     * Knife4j Hello to test interface
     * WeChat official account: Java technology stack
     * Author: stack length
    @ApiImplicitParam(name = "name", value = "name", required = true)
    @ApiOperation(value = "official account Java The technology stack says hello to you!")
    @ApiOperationSupport(order = 2, author = "Stack length")
    public ResponseEntity<String> hello(@RequestParam(value = "name") String name) {
        return ResponseEntity.ok("Hi:" + name);

     * Knife4j Test interface login
     * WeChat official account: Java technology stack
     * Author: stack length
            @ApiImplicitParam(name = "username", value = "user name", required = true),
            @ApiImplicitParam(name = "password", value = "password", required = true)
    @ApiOperation(value = "Interface login!")
    @ApiOperationSupport(order = 1, author = "Stack length")
    public ResponseEntity<String> login(@RequestParam(value = "username") String username,
                                        @RequestParam(value = "password") String password) {
        if (StringUtils.isNotBlank(username) && "javastack".equals(password)) {
            return ResponseEntity.ok("Login succeeded:" + username);
        return ResponseEntity.ok("Incorrect user name or password:" + username);


In order to support the interface sequence and interface author, Knife4j's @ ApiOperationSupport annotation is used above, and others are Swagger's own annotations. From this directory, the following annotations are also supported:

More can be learned on the official website.

The complete Demo code will not be posted one by one. All the actual combat source codes of this tutorial have been uploaded to this warehouse:

4. Knife4j test

Start the application and open the Knife4j document page:


Login authentication

Home page information

Some configured document parameters and interface statistics will be displayed on the home page, and the two interfaces of our test module can also be seen in the module menu on the home page.

Interface documentation:

Login interface documentation

Hello interface document


Login failed

Login succeeded

Say hello to success

Here, the stack leader uses interface sorting and interface author function. In addition, it also supports many powerful functions such as grouping sorting, custom documents, Swagger resource protection, export Markdown, parameter cache, etc. there are up to 29 enhancements. Those who are interested can try it by themselves


Well, today, the stack leader introduced to you an open source Knife4j project of Chinese programmers, that is, the enhanced version of Swagger. There is no doubt that it is more powerful and better used than Swagger UI, which is also in line with Chinese habits!

If you are also using Swagger, you can consider using Knife4j. It not only has a more powerful UI, but also has up to 29 enhancements. They are not a substitute relationship. Just like the relationship between Mybatis Plus and Mybatis, it can help you further improve development productivity.

If you are also using Knife4j, please leave a message to share!

All the actual combat source code of this tutorial has been uploaded to this warehouse:

Copyright notice: This article is the public number "Java technology stack" original, original is not easy, reprint, quote the content of this article please indicate the source, all the plagiarism official account + complaint, and retain the right to pursue its legal responsibility.

Posted on Fri, 19 Nov 2021 08:22:08 -0500 by ropic