当前位置：首页 > news >正文

Springboot 整合 Knife4j （API文档生成工具）

news 2025/7/24 4:58:54

一、Knife4j 介绍

二、Springboot 整合 Knife4j

1、pom.xml中引入依赖包

2、在application.yml 中添加 Knife4j 相关配置

3、打开 Knife4j UI界面

三、关于Knife4j框架中常用的注解

1、@Api

2、@ApiOperation

3、@ApiOperationSupport(order = X)

4、@ApiImplicitParam

5、@ApiModel / @ApiModelProperty

四、支持接口调试

五、离线下载

一、Knife4j 介绍

Knife4j 是一个基于 Swagger 构建的开源 Java API 文档工具，主要包括两大核心功能：文档说明和在线调试。使用简单的配置和注解就可以节省写接口文档的时间了，舒服！😄😄😄

二、Springboot 整合 Knife4j

1、pom.xml 中引入依赖包

        <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi2-spring-boot-starter</artifactId><version>4.4.0</version></dependency>

2、在 application.yml 中添加 Knife4j 相关配置

server:port: 5555knife4j:enable: trueopenapi:title: 接口文档description: "接口文档生成"email: ""concat: adminurl: https://docs.xiaominfo.comversion: v4.0license: Apache 2.0license-url: https://stackoverflow.com/terms-of-service-url: https://stackoverflow.com/group:test1:group-name: 分组名称api-rule: packageapi-rule-resources:- com.example.springbootzy

3、打开 Knife4j UI界面

浏览器地址栏输入：http://127.0.0.1:服务端口号/doc.html

三、关于Knife4j框架中常用的注解

1、@Api

作用于Controller类上，通过此注解的tags属性，可以指定模块名称，并且模块名称前添加数字， Knife4j会根据这些数字将各个模块做升序排列。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {@PostMapping("/queryByCondition")public String queryByCondition(@RequestBody QueryCondition queryCondition) {return "this is common demo";}
}@RestController
@RequestMapping("/user")
@Api(tags= "02 用户模块")
public class UserController {@PostMapping("/queryUser")public String queryUser(@RequestBody QueryCondition queryCondition) {return "this is user demo";}
}@Api(tags= "03 公司模块")
@RestController
@RequestMapping("/company")
public class CompanyController {@PostMapping("/queryCompany")public String queryCompany(@RequestBody QueryCondition queryCondition) {return "this is company demo";}
}

2、@ApiOperation

作用于 Controller 类中的方法上，用于描述 API 接口的功能和作用。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {@ApiOperation("根据条件查询数据")@PostMapping("/queryByCondition")public String queryByCondition(@RequestBody QueryCondition queryCondition) {return "this is common demo";}
}

3、@ApiOperationSupport(order = X)

作用于 Controller 类中的方法上，通过此注解的 order 属性（int），可以指定排序序号。

@RequestMapping("/common")
@RestController
@Api(tags= "01 通用模块")
public class CommonController {@ApiOperation("根据条件查询数据")@ApiOperationSupport(order = 2)@PostMapping("/queryByCondition")public String queryByCondition(@RequestBody QueryCondition queryCondition) {return "this is common demo";}@ApiOperation("保存")@ApiOperationSupport(order = 3)@PostMapping("/add")public String add(@RequestBody QueryCondition queryCondition) {return "this is add";}@ApiOperation("更新")@ApiOperationSupport(order = 1)@PostMapping("/update")public String update(@RequestBody QueryCondition queryCondition) {return "this is update";}
}

4、@ApiImplicitParam

作用于 Controller 类中的方法上，用于描述方法入参的详细信息。

@ApiOperation("根据主键ID查询")@ApiOperationSupport(order = 4)@ApiImplicitParam(name = "id", value = "主键ID", required = true, dataType = "Long", paramType = "path")@PostMapping("/queryById/{id}")public String queryById(@PathVariable Long id) {return "this is queryById";}

5、@ApiModel / @ApiModelProperty

@ApiModel：作用于 POJO 类上，描述该对象的作用。

@ApiModelProperty：作用于 POJO 类的属性上，描述参数信息。

@ApiModel("通用查询条件实体")
@Data
public class QueryCondition {@ApiModelProperty(value = "页码", required = true, example = "1")private Integer pageSize;@ApiModelProperty(value = "每页显示数量", required = true, example = "20")private Integer pageNum;@ApiModelProperty(value = "主键ID", required = false, example = "1",dataType ="Long")private Long id;@ApiModelProperty(value = "名称", required = false, example = "张三")private String name;
}