SpringBoot 整合 Knife4j

一、SpringDoc 和 Knife4j 配置

1. 项目目录

2. pom.xml

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

<!-- Springboot 3.x 版本 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.3.0</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Springboot 2.x 版本 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>

3. application.yml

server:
  port: 8888

springdoc:
  api-docs:
    # swagger 后端请求地址
    path: /v3/api-docs
    # 是否开启文档功能
    enabled: true
  # 定义分组，可定义多个，也可以不定义
  group-configs:
    - group: 系统模块
      paths-to-match: '/system/**'
      packages-to-scan: com.cnbai.system
    - group: 业务模块
      paths-to-match: '/web/**'
      packages-to-scan: com.cnbai.web

knife4j:
  enable: true

4. 创建配置类

OpenApiConfig

package com.cnbai.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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.net.Inet4Address;
import java.net.InetAddress;

/**
 * OpenApi 配置
 */
@Configuration
public class OpenApiConfig implements WebMvcConfigurer, CommandLineRunner {

    private static final Logger logger = LoggerFactory.getLogger(OpenApiConfig.class);

    @Value("${server.port}")
    private Integer port;

    @Bean
    public OpenAPI configOpenApi() {
        return new OpenAPI()
                .info(new Info().title("API接口文档")
                        .description("test项目接口文档")
                        .version("v1.0")
                        .contact(new Contact().name("cnbai")));
    }

    /**
     * 拦截器过滤静态资源
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 项目启动打印 swagger 路径
     */
    @Override
    public void run(String... args) throws Exception {
        final InetAddress localHost = Inet4Address.getLocalHost();
        String path = "http://" + localHost.getHostAddress() + ":" + port + "/doc.html";
        logger.info("Swagger-UI: {}", path);
    }
}

4. 创建系统模块类

SysController

package com.cnbai.system;

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

@Tag(name = "系统用户接口")
@RestController
@RequestMapping("/system")
public class SysController {

    @Operation(summary = "系统用户查询")
    @GetMapping("/find")
    public String find() {
        return "查询";
    }

    @Operation(summary = "系统用户新增")
    @PostMapping("/add")
    public SysUser add(SysUser user) {
        return user;
    }

    @Operation(summary = "系统用户删除")
    @DeleteMapping("/delete")
    public void delete() {
        System.out.println("delete");
    }
}

SysUser

package com.cnbai.system;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(name = "SysUser", description = "系统用户")
public class SysUser {

    @Schema(description = "主键")
    private int id;

    @Schema(description = "用户名")
    private String name;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

4. 创建业务模块类

WebController

package com.cnbai.web;

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

@Tag(name = "用户接口")
@RestController
@RequestMapping("/web")
public class WebController {

    @Operation(summary = "用户查询")
    @GetMapping("/find")
    public String find() {
        return "查询";
    }

    @Operation(summary = "用户新增")
    @PostMapping("/add")
    public User add(User user) {
        return user;
    }

    @Operation(summary = "用户删除")
    @DeleteMapping("/delete")
    public void delete() {
        System.out.println("delete");
    }
}

User

package com.cnbai.web;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(name = "User", description = "用户")
public class User {

    @Schema(description = "主键")
    private int id;

    @Schema(description = "用户名")
    private String name;

    @Schema(description = "电话")
    private String phone;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPhone() {
        return phone;
    }

    public void setPhone(String phone) {
        this.phone = phone;
    }
}

5. 创建启动类

package com.cnbai;

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

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

6. 访问 Swagger 地址

http://localhost:8888/doc.html

二、将接口文档导入到 ApiFox 中

1. 创建项目并进入

2. 选择导入数据-定时导入

3. 配置导入任务

4. 执行导入任务

5. 导入完成