跳转至

关于Knife4j Next

约 155 个字 52 行代码 预计阅读时间 1 分钟

介绍

Knife4j Next是更现代的Knife4j，延续熟悉的doc.html接入方式，持续修复Spring Boot 2.7 / 3.x / 4.x的兼容性。这是Knife4j的社区维护fork

引入依赖

SpringBoot 3.5.x引入下面的依赖，其他版本参考文档：

XML
1
2
3
4
5
<dependency>
    <groupId>com.baizhukui</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>5.2.2</version>
</dependency>

创建配置类

Java
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
@Configuration
public class Knife4jConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                  .title("xx系统 API")
                  .version("1.0")
                  .description("这是一个基于SpringBoot的xx系统API文档"));
    }
}

修改配置文件

knife4j是在Swagger上做的增强，同样支持SpringDoc，开发者即可完全参考springdoc-openapi的项目说明

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
springdoc:
  packages-to-scan: com.example.demo
  paths-to-match: /api/**
  swagger-ui:
    tags-sorter: alpha
    operations-sorter: alpha
knife4j:
  enable: true
  production: false # 不用于生产环境
  setting:
    language: zh_cn # 文档语言为中文

Controller代码

Java
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@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)
   })
   // in = ParameterIn.QUERY表示参数在请求字符串中，in = ParameterIn.PATH表示参数在请求路径中
   // in = ParameterIn.HEADER表示参数在请求头中
   @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);
   }
}

导入API到Postman

在Postman的工作区中点击import，然后输入http://ip:port/v3/api-docs，Postman会自动识别出所有的API，访问http://ip:port/doc.html可以看到在线版调试平台