Java Knife4j案例如何整合项目

wen java案例 2026-06-29 228

本文目录导读：

环境准备
配置文件
配置类
实体类示例
Controller示例
启动类配置
访问Knife4j UI
高级配置选项
常见问题处理

我将为您详细介绍如何在Java项目中整合Knife4j（Swagger的增强工具），以下是完整的整合案例：

环境准备

Maven项目 - 添加依赖

在 pom.xml 中添加以下依赖：

<!-- Knife4j 核心依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<!-- Spring Boot Web 依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Gradle项目 - 添加依赖

// Knife4j 核心依赖
implementation 'com.github.xiaoymin:knife4j-spring-boot-starter:3.0.3'
// Spring Boot Web 依赖
implementation 'org.springframework.boot:spring-boot-starter-web'

配置文件

application.yml 配置

server:
  port: 8080
spring:
  application:
    name: knife4j-demo
# Knife4j 配置
knife4j:
  enable: true
  production: false
  setting:
    language: zh-CN
    enable-dynamic-parameter: true  # 启用动态参数
    enable-swagger-models: true
    swagger-model-name: 实体类列表
# Swagger 配置
swagger:
  enable: true API文档
  description: 项目接口文档
  version: 1.0.0
  base-package: com.example.controller
  contact:
    name: 开发者
    url: https://example.com
    email: dev@example.com

application.properties 配置

server.port=8080
# Knife4j 配置
knife4j.enable=true
knife4j.production=false
knife4j.setting.language=zh-CN
knife4j.setting.enable-dynamic-parameter=true
knife4j.setting.enable-swagger-models=true
# Swagger 配置
swagger.enable=true
swagger.title=API文档
swagger.description=项目接口文档
swagger.version=1.0.0
swagger.base-package=com.example.controller

配置类

SwaggerConfiguration.java

package com.example.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.*;
@Configuration
@EnableSwagger2
@EnableKnife4j
public class SwaggerConfiguration {
    @Value("${swagger.base-package}")
    private String basePackage;
    @Value("${swagger.title}")
    private String title;
    @Value("${swagger.description}")
    private String description;
    @Value("${swagger.version}")
    private String version;
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描的包路径
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build()
                .securityContexts(securityContexts())
                .securitySchemes(securitySchemes());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(new Contact("开发者", "https://example.com", "dev@example.com"))
                .version(version)
                .build();
    }
    // 配置JWT认证
    private List<SecurityScheme> securitySchemes() {
        return Arrays.asList(
                new ApiKey("Authorization", "Authorization", "header")
        );
    }
    private List<SecurityContext> securityContexts() {
        return Arrays.asList(
                SecurityContext.builder()
                        .securityReferences(securityReferences())
                        .forPaths(path -> path.contains("/api/"))
                        .build()
        );
    }
    private List<SecurityReference> securityReferences() {
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = new AuthorizationScope("global", "accessEverything");
        return Arrays.asList(
                new SecurityReference("Authorization", authorizationScopes)
        );
    }
}

实体类示例

User.java

package com.example.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel(value = "用户实体", description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    @ApiModelProperty(value = "用户名", example = "张三")
    private String username;
    @ApiModelProperty(value = "年龄", example = "25")
    private Integer age;
    @ApiModelProperty(value = "邮箱", example = "zhangsan@example.com")
    private String email;
    @ApiModelProperty(value = "手机号", example = "13800138000")
    private String phone;
}

Controller示例

UserController.java

package com.example.controller;
import com.example.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import java.util.*;
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理接口")
public class UserController {
    @GetMapping
    @ApiOperation(value = "获取用户列表", notes = "分页查询用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "页码", required = true, paramType = "query", dataType = "int", example = "1"),
        @ApiImplicitParam(name = "size", value = "每页数量", required = true, paramType = "query", dataType = "int", example = "10")
    })
    @ApiResponses({
        @ApiResponse(code = 200, message = "成功返回用户列表"),
        @ApiResponse(code = 400, message = "请求参数错误"),
        @ApiResponse(code = 500, message = "服务器内部错误")
    })
    public Map<String, Object> listUsers(@RequestParam(defaultValue = "1") int page,
                                         @RequestParam(defaultValue = "10") int size) {
        List<User> users = new ArrayList<>();
        // 模拟数据
        User user = new User();
        user.setId(1L);
        user.setUsername("张三");
        user.setAge(25);
        user.setEmail("zhangsan@example.com");
        user.setPhone("13800138000");
        users.add(user);
        Map<String, Object> result = new HashMap<>();
        result.put("data", users);
        result.put("total", 1);
        result.put("page", page);
        result.put("size", size);
        return result;
    }
    @GetMapping("/{id}")
    @ApiOperation(value = "根据ID获取用户", notes = "根据用户ID获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "long")
    public User getUserById(@PathVariable Long id) {
        User user = new User();
        user.setId(id);
        user.setUsername("张三");
        user.setAge(25);
        return user;
    }
    @PostMapping
    @ApiOperation(value = "创建用户", notes = "创建一个新用户")
    public User createUser(@RequestBody @ApiParam(value = "用户信息", required = true) User user) {
        user.setId(new Random().nextLong());
        return user;
    }
    @PutMapping("/{id}")
    @ApiOperation(value = "更新用户", notes = "更新用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "long")
    public User updateUser(@PathVariable Long id, @RequestBody @ApiParam(value = "用户信息", required = true) User user) {
        user.setId(id);
        return user;
    }
    @DeleteMapping("/{id}")
    @ApiOperation(value = "删除用户", notes = "根据ID删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, paramType = "path", dataType = "long")
    public String deleteUser(@PathVariable Long id) {
        return "用户 " + id + " 已删除";
    }
}

启动类配置

Application.java

package com.example;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

访问Knife4j UI

启动项目后,访问以下地址：

http://localhost:8080/doc.html

高级配置选项

添加请求头参数

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            // ... 其他配置
            .globalRequestParameters(
                Arrays.asList(
                    new RequestParameterBuilder()
                        .name("token")
                        .description("用户令牌")
                        .in(ParameterType.HEADER)
                        .required(true)
                        .build()
                )
            );
}

分组配置

@Bean
public Docket adminApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("管理端API")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.admin"))
            .paths(PathSelectors.ant("/admin/**"))
            .build();
}
@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户端API")
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.user"))
            .paths(PathSelectors.ant("/api/**"))
            .build();
}

常见问题处理

解决静态资源冲突

spring:
  mvc:
    static-path-pattern: /static/**
  resources:
    static-locations: classpath:/static/

配置白名单

knife4j:
  basic:
    enable: true
    username: admin
    password: admin123

这样就完成了Knife4j在Java项目中的完整整合,访问 http://localhost:8080/doc.html 即可看到美观的API文档界面。

本文地址： https://www.bmjup.com/post/11626.html

版权声明：足球直播足球直播足球直播足球直播足球直播中超直播中超直播中超直播中超直播中超直播英超直播英超直播英超直播英超直播英超直播德甲直播德甲直播德甲直播德甲直播德甲直播西甲直播西甲直播西甲直播西甲直播西甲直播意甲直播意甲直播意甲直播意甲直播意甲直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播篮球直播篮球直播篮球直播篮球直播篮球直播足球直播足球直播足球直播足球直播足球直播中超直播中超直播中超直播中超直播中超直播英超直播英超直播英超直播英超直播英超直播德甲直播德甲直播德甲直播德甲直播德甲直播西甲直播西甲直播西甲直播西甲直播西甲直播意甲直播意甲直播意甲直播意甲直播意甲直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播篮球直播篮球直播篮球直播篮球直播篮球直播足球直播足球直播足球直播足球直播足球直播中超直播中超直播中超直播中超直播中超直播英超直播英超直播英超直播英超直播英超直播德甲直播德甲直播德甲直播德甲直播德甲直播西甲直播西甲直播西甲直播西甲直播西甲直播意甲直播意甲直播意甲直播意甲直播意甲直播 NBA直播 NBA直播 NBA直播 NBA直播 NBA直播篮球直播篮球直播篮球直播篮球直播篮球直播