跳转至

关于Knife4j

约 81 个字 54 行代码 预计阅读时间 1 分钟

引入依赖

XML
1
2
3
4
5
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</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
12
13
springdoc:
  api-docs:
    path: /v3/api-docs  # 更改 OpenAPI JSON/YAML 描述文件的路径，默认是 /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html  # 更改 Swagger UI 页面的访问路径，默认是 /swagger-ui.html
  packages-to-scan: org.epsda.forum.controller  # 指定要扫描的包名列表（逗号分隔），只生成这些包下的接口文档
  paths-to-match: /**  # 指定要匹配的请求路径模式（Ant 风格），仅对符合该规则的接口生成文档
# 以下是knife4j的增强配置
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