Knife4j Simple Practice

Knife4j is an enhanced solution that combines Swagger2 and OpenAPI3. In this article, we will simply practice Knife4j.

About Knife4j

Before changing its name to Knife4j, the original name was swagger-bootstrap-ui. The Development language & Framework of Knife4j is Java、JavaScript、Vue and swagger-bootstrap-ui is Java、JavaScript、jQuery.

Spring Boot Version Compatibility

Spring Boot Version	Knife4j Swagger2	Knife4j OpenAPI3
1.5.x~2.0.0		>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

In this article, we will use spring Boot 3.x and JDK 17 to simple practice. The version of Knife4j is 4.5.0(latest)

Maven dependency

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

Practice

Before coding, we can set our file header information.

Create Project

pom.xml File

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- The parent dependency -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.3</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <groupId>io.github.charlie</groupId>
    <artifactId>knife4j-practice</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

        <!-- tool -->
        <hutool.version>5.8.26</hutool.version>

        <knife4j.version>4.5.0</knife4j.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>

        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>${hutool.version}</version>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-core</artifactId>
            <version>2.2.7</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-dependencies</artifactId>
            <version>${knife4j.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven-compiler-plugin.version}</version>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

MainApplication.java and application.yml

Create MainApplication.java

package io.github.charlie;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

_/**_
_ * @Author: Charlie Zhang(Github: @charlie-zhang-code)_
_ * @Date: 2025/1/6_
_ * @Description: TODO_
_ */_
@SpringBootApplication
public class MainApplication {
    public static void main(String[] args) {
        SpringApplication._run_(MainApplication.class, args);
    }
}

Create aapplication.yml

server:
  port: 8086

spring:
  main:
    allow-circular-references: true
  application:
    name: knight-practice-demo

Setup the Spring Boot application

Visit URL http://localhost:8080/doc.html#/home, the following page will appear

Basic Config of Knife4j

server:
  port: 8086

spring:
  main:
    allow-circular-references: true
  application:
    name: knight-practice-demo

_# springdoc-openapi项目配置_
springdoc:
  swagger-ui:
    path: /swagger-ui.html _# the path of swagger-ui_
_    _tags-sorter: alpha _# sort tags_
_    _operations-sorter: alpha _# sort operations_
_  _api-docs:
    path: /v3/api-docs _# the path of api-docs_
_  _group-configs:
    - group: 'default' _# default group_
_      _paths-to-match: '/**' _# the path to match_
_      _packages-to-scan: io.github.charlie.controller _# the package to scan_
_# knife4j的增强配置，不需要增强可以不配_
knife4j:
  enable: true

Config Knife4j uses java code

Create SwaggerConfig class

package io.github.charlie.config;

import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

_/**_
_ * @Author: Charlie Zhang(Github: @charlie-zhang-code)_
_ * @Date: 2025/1/6_
_ * @Description: TODO_
_ */_
@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Demo Api")
                        .version("1.0")
                        .contact(new Contact().name("Charlie Zhang"))
                        .description("Knife4j springdoc-openapi demo"));
    }
}