Knife4j简单使用

Knife4j 是 基于 Swagger 构建的增强型 API 文档工具，专为 Java 后端项目（尤其 Spring Boot）设计，提供可视化、交互式的 API 调试与管理能力。

springboot下集成knife4j

一、引入相关依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version> <!-- 版本可按需更新 -->
</dependency>

二、创建配置类

package com.yuhuan.book.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class Knife4jConfiguration {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("图书管理系统API")
                        .version("1.0")
                        .description("图书管理系统项目的接口文档"));
    }

    @Bean
    public GroupedOpenApi userAPI() {
        return GroupedOpenApi.builder().group("用户信息管理").
                pathsToMatch("/user/**").
                build();
    }

    @Bean
    public GroupedOpenApi systemAPI() {
        return GroupedOpenApi.builder().group("图书管理").
                pathsToMatch("/book/**").
                build();
    }
}

三、创建user控制器

package com.yuhuan.book.controller;

import com.yuhuan.book.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user")
@Tag(name = "用户信息管理")
public class UserController {
    @GetMapping("/getUserById")
    @Operation(summary = "根据id获取user信息")
    public User getUser(@Parameter(description = "用户id") @RequestParam("id") Integer id){
        User user = new User();
        user.setName("扈三娘");
        user.setAge(28);
        user.setEmail("hsn@123.com");
        return user;
    }
}

四、运行项目，查看knife4j的效果

四、常用注解速查表（快速查阅）

注解	作用位置	核心作用	关键属性
@Tag	Controller 类	接口模块分组 / 描述	name（分组名）、description
@Operation	Controller 方法	接口摘要 / 响应规则	summary、description、responses
@Parameter	方法参数	非请求体参数说明（路径 / 查询 / 请求头）	name、in、description、required、example
@Parameters	Controller 方法	批量配置 @Parameter	value（@Parameter 数组）
@Schema	DTO 类 / 字段	实体类 / 字段说明、格式限制	description、required、example、hidden
@ApiResponse	@Operation 内	单个响应状态码说明	responseCode、description
@Hidden	类 / 方法 / 字段	隐藏文档中的元素	无（默认 true）
@SecurityRequirement	类 / 方法	标记接口需要的权限	name（权限方案名）