1、pom文件
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>2、SwaggerConfig
package com.example.demo.config;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("用户管理系统API文档")
.description("基于Knife4j的API文档")
.version("1.0")
.build();
}
}3、application.yml
# Knife4j API文档配置
knife4j:
enable: true
setting:
language: zh-CN
production: false
basic:
enable: false
username: admin
password: 1234564、使用样例
package com.example.demo.controller;
import cn.hutool.core.util.StrUtil;
import cn.hutool.json.JSONUtil;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.example.demo.entity.User;
import com.example.demo.request.UserRequest;
import com.example.demo.response.UserResponse;
import com.example.demo.service.UserService;
import com.example.demo.vo.UserOrderVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
import java.util.HashMap;
/**
* User API controller
*/
@RestController
@Api(tags = "用户管理")
public class UserController {
@Autowired
private UserService userService;
/**
* Single table pagination query user interface
* @param pageNum Page number (default 1)
* @param pageSize Page size (default 10)
* @param age Age (optional)
* @return Pagination result
*/
@GetMapping("/user/page")
public IPage<User> getUserPage(
@RequestParam(defaultValue = "1", name = "pageNum") @ApiParam(value = "Page number", defaultValue = "1") Integer pageNum,
@RequestParam(defaultValue = "10", name = "pageSize") @ApiParam(value = "Page size", defaultValue = "10") Integer pageSize,
@RequestParam(required = false) @ApiParam(value = "Age") Integer age) {
return userService.getUserPage(pageNum, pageSize, age);
}
/**
* Multi-table join pagination query interface (User + Order)
* @param pageNum Page number (default 1)
* @param pageSize Page size (default 10)
* @param username Username (optional)
* @return Pagination result
*/
@GetMapping("/user/joinPage")
@ApiOperation(value = "联合分页查询", notes = "联合分页查询")
public IPage<UserOrderVO> getUserOrderPage(
@RequestParam(defaultValue = "1", name = "pageNum") @ApiParam(value = "Page number", defaultValue = "1") Integer pageNum,
@RequestParam(defaultValue = "10", name = "pageSize") @ApiParam(value = "Page size", defaultValue = "10") Integer pageSize,
@RequestParam(required = false) @ApiParam(value = "Username") String username) {
return userService.getUserOrderPage(pageNum, pageSize, username);
}
@PostMapping("/user/add")
@ApiOperation(value = "新增用户", notes = "新增用户")
public void addUser(@RequestBody @ApiParam(value = "User information") UserRequest request) {
User user = new User();
BeanUtils.copyProperties(request, user);
if(request.getExt() != null && !request.getExt().isEmpty()){
user.setExtJson(JSONUtil.toJsonStr(request.getExt()));
}
userService.save(user);
}
@GetMapping("/user/detail")
@ApiOperation(value = "用户详情", notes = "用户详情")
public UserResponse getUserDetail(@RequestParam Long id) {
User user = userService.getById(id);
UserResponse response = new UserResponse();
BeanUtils.copyProperties(user, response);
if(StrUtil.isNotEmpty(user.getExtJson())){
response.setExt(JSONUtil.toBean(user.getExtJson(), Map.class));
}
return response;
}
}5、启动类打印接口文档地址
package com.example.demo;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.core.env.Environment;
import java.net.InetAddress;
import java.net.NetworkInterface;
import java.net.UnknownHostException;
import java.util.Enumeration;
/**
* 项目启动类
* @MapperScan：扫描Mapper接口所在包
*/
@SpringBootApplication
@MapperScan("com.example.demo.mapper")
public class SpringbootMpDemoApplication {
public static void main(String[] args) {
// 启动Spring Boot应用，并获取应用上下文
ConfigurableApplicationContext context = SpringApplication.run(SpringbootMpDemoApplication.class, args);
// 从上下文获取环境配置（包含端口、IP等配置）
Environment env = context.getEnvironment();
// 1. 获取项目端口（优先读取配置的server.port，默认8080）
String port = env.getProperty("server.port", "8080");
// 2. 获取本机真实IP（排除127.0.0.1，适配多网卡场景）
String ip = getLocalIpAddress();
// 3. 打印完整的访问地址
System.out.println("=========================================================");
System.out.println("项目启动成功！🎉 接口文档访问地址：http://" + ip + ":" + port+"/doc.html");
System.out.println("=========================================================");
}
/**
* 获取本机真实的IPv4地址（非回环地址，适配多网卡）
* @return 本机IP地址，异常时返回127.0.0.1
*/
private static String getLocalIpAddress() {
try {
// 遍历所有网络接口
Enumeration<NetworkInterface> interfaces = NetworkInterface.getNetworkInterfaces();
while (interfaces.hasMoreElements()) {
NetworkInterface ni = interfaces.nextElement();
Enumeration<InetAddress> addresses = ni.getInetAddresses();
// 遍历当前网卡的所有IP地址
while (addresses.hasMoreElements()) {
InetAddress addr = addresses.nextElement();
// 过滤条件：非回环地址（排除127.0.0.1）+ 是IPv4地址（排除IPv6）
if (!addr.isLoopbackAddress() && addr.getHostAddress().indexOf(":") == -1) {
return addr.getHostAddress();
}
}
}
// 如果没找到有效IP，返回本机localhost的IP
return InetAddress.getLocalHost().getHostAddress();
} catch (UnknownHostException e) {
return "127.0.0.1";
} catch (Exception e) {
return "127.0.0.1";
}
}
}