Springboot整合Knife4j接口文档

本文主要是介绍Springboot整合Knife4j接口文档，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！

一、knife4j是什么

Knife4j是一个基于SpringBoot构建的文档生成工具，旨在为Java MVC框架集Swagger2 和 OpenAPI3为一体的增强解决方案。**

二、快速开始

1.Spring Boot 3版本

• Spring Boot 3 只支持OpenAPI3规范
• Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
• JDK版本必须 >= 17
• 详细Demo请参考knife4j-spring-boot3-demo

1.引入依赖

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

2.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.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:enable: truesetting:language: zh_cn

3.示例代码

@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);}
}

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

2.Spring Boot 3版本

• Spring Boot 版本建议 2.4.0~3.0.0之间
• Spring Boot 版本 < 2.4 版本则建议选择Knife4j 4.0之前的版本
• Spring Boot 2 + OpenAPI2 demo:knife4j-spring-boot27-demo
• Spring Boot 2 + OpenAPI3 demo:knife4j-springdoc-openapi-demo

1.引入依赖

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

2.yml配置

knife4j:enable: trueopenapi:title: Knife4j官方文档description: "`我是测试`,**你知道吗**# aaa"email: xiaoymin@foxmail.comconcat: 八一菜刀url: 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.knife4j.demo.new3

3.4. 注解使用

@Api(tags = “01.用户管理模块”)

@Api标注在Controller类上，在页面上接口文档页面上会分类替代Controller名称

@ApiOperation(value=“查询列表”)

@ApiOperation标注在Controller方法上，在接口文档页面会显示value内容替代方法名

@ApiModelProperty(value = “用户名”, required = true, example = “赵丽颖”)

@ApiModelProperty标注在入参的dto变量上，value会替代具体参数名称，required会显示是否必填项，example会给出默认值

@ApiImplicitParam(name = “id”, value = “微博”, required=true, dataType = “int”)

@ApiImplicitParam标注在Controller方法上，对未封装参数进行注释，value会替代具体参数名称，required会显示是否必填项，dataType 指定参数类型

@ApiIgnore

@ApiIgnore标注在Controller方法的入参上，被标注的参数表示忽略该参数，不会在接口文档中显示，例如HttpRequest参数不需要显示。

最后，访问Knife4j的文档地址：http://ip:port/doc.html即可查看文档

这篇关于Springboot整合Knife4j接口文档的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！

---