本文目录导读：
我将为您详细介绍如何在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文档界面。
