Knife4j的环境配置

最新推荐文章于 2025-09-23 16:41:24 发布

原创最新推荐文章于 2025-09-23 16:41:24 发布 · 1.5k 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#java #经验分享

Knife4j的环境配置

Knife4j在搭建环境阶段动辄出错，现在总结最重要的一些环境配置。配置都是固定的，最好别改。

依赖项（pom文件）

注意点：基于jdk17、Springboot3.x版本、knife4j-openapi3版本。Springboot3.x版本必须搭配knife4j-openapi3版本。Springboot2.x版本则搭配knife4j-openapi2版本。

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.4</version>
        <relativePath/>
    </parent>
    <groupId>com.tencent</groupId>
    <artifactId>demo4</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo4</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>17</java.version>
        <!-- 使用 Knife4j 推荐的最新版本 -->
        <knife4j.version>4.4.0</knife4j.version>
    </properties>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Knife4j (基于 SpringDoc) -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>${knife4j.version}</version>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

config文件（Configuration配置类）

package com.example.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 io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfiguration {
    /**
     * 配置OpenAPI基本信息（必选）
     */
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API文档标题")
                        .version("1.0")
                        .description(description())
                        .contact(new Contact()
                                .name("开发者")
                                .email("dev@example.com")
                                .url("https://example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://springdoc.org")));
    }

    /**
     * 用户模块API分组（示例）
     */
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("用户管理")
                .packagesToScan("com.example.controller") // 替换为你的实际包路径
                .pathsToMatch("/user/**")
                .build();
    }

    /**
     * 产品模块API分组（示例）
     */
    @Bean
    public GroupedOpenApi productApi() {
        return GroupedOpenApi.builder()
                .group("产品管理")
                .packagesToScan("com.example.product.controller") // 替换为你的实际包路径
                .pathsToMatch("/product/**")
                .build();
    }

    /**
     * 公共模块API分组（可选）
     */
    @Bean
    public GroupedOpenApi commonApi() {
        return GroupedOpenApi.builder()
                .group("公共服务")
                .pathsToMatch("/common/**")
                .build();
    }

    /**
     * 文档描述（支持Markdown语法）
     */
    private String description() {
        return """
                # 系统API文档
                
                - **用户管理**：用户注册、登录、权限管理
                - **产品管理**：产品CRUD操作
                - **公共服务**：文件上传、短信发送等
                
                > 注意：生产环境请关闭文档！
                """;
    }
}