引言
Knife4j 是基于 Swagger 的增强版API文档生成工具，提供美观且功能丰富的API文档界面。
官网：Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j (xiaominfo.com)
配置
基于SpringBoot3进行配置，有以下注意点：
- SpringBoot3 只支持OpenAPI3规范
- Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
- JDK版本必须 >= 17
在 IDEA 中新建一个 SpringBoot 项目，在pom.xml中引入 Knife4j 依赖：
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version>
</dependency>
在配置文件application.yml中配置：
# springdoc-openapi项目配置
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsgroup-configs:- group: 'default'paths-to-match: '/**'#此处为要扫描的包路径packages-to-scan: com.example.controller
# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn
使用
Knife4j 文档地址：IP+端口号+/doc.html，实例：http://localhost:8080/doc.html
使用OpenAPI3的规范注解注释接口，示例：
@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {@Operation(summary = "普通body请求")@PostMapping("/body")public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){return ResponseEntity.ok(fileResp);}@Operation(summary = "普通body请求+Param+Header+Path")@Parameters({@Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),@Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),@Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)})@PostMapping("/bodyParamHeaderPath/{id}")public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);return ResponseEntity.ok(fileResp);}
}
进入文档界面如下：
在此界面可以进行接口调试等操作。
