我是洋哥，一个拥有6年经验的程序员，Litchi开源组织发起人
在日常开发中，写接口文档是我们必不可少的，接口是前后端开发联调的桥梁。当然，接口维护是消耗时间成本的，作为后端开发，挑选一款界面友好，使用方便，免维护的接口文档工具是至关重要的
knif4j是什么？
knif4j是为java Mvc框架集成Swagger生成API文档的增强解决方案,其前身是swagger-bootstrap-ui，取名为knif4j是希望它能像一把匕首一样小巧、轻量,并且功能强悍。其底层是对springfox的封装,使用方式 也和springfox一致,只是它对接口文档UI进行了优化。
核心功能
knif4j 具有以下两点核心功能：
- 文档说明： 根据swagger的规范说明,详细列出了接口文档的说明,包括：接口地址、类型、请求示例、请求参数 响应示例、响应参数、响应码等信息,对该接口的使用情况一目了然。
- 在线调试： 提供在线接口联调的强大功能,自动解析当前接口参数,同时包含：表单验证,调用参数可返回接口响应内容、headers、响应时间、响应状态码等信息，帮助开发者在线调试。
优势
- 兼容OpenAPI 2.0和3.0
- 基础ui组件(自定义文档、动态参数调试、I18n、接口排序、导出等)
- 基于Springdoc-openapi+OAS3规范的自动注入starter
- 提供对主流网关组件的统一聚合OpenAPI接口文档的解决方案
- 基于Springdoc-openapi项目提供OAS3规范的增强扩展
- 提供基于K8S+Docker的云原生的聚合OpenAPI文档的解决方案
SpringBoot3.2集成knif4j实战
上面说了knif4j的核心功能和优势，光说不练假把式，我们动起来，下面我以litchi-admin项目为例，详细介绍集成过程，项目源代码地址传送门：gitee.com/litchi365/l… （给个star哦！）
1、引入依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.4.0</version>
</dependency>
2、配置application.yml
#springdoc相关配置
springdoc:
swagger-ui:
tags-sorter: alpha
operations-sorter: alpha
api-docs:
path: /v3/api-docs
enabled: true
group-configs:
- group: 'Litchi-Admin接口'
paths-to-match: '/**'
packages-to-scan: com.litchi #按包路径匹配:一般到启动类的包名
#knife4j相关配置 可以不用改
knife4j:
enable: true #开启knife4j，无需添加@EnableKnife4j注解
setting:
language: zh_cn #中文
swagger-model-name: 实体类 #重命名SwaggerModel名称,默认
3、在启动类中添加@EnableKnife4j
@EnableKnife4j
@SpringBootApplication
public class LitchiAdminApplication {
public static void main(String[] args) {
SpringApplication.run(LitchiAdminApplication.class, args);
}
}
4、配置OpenApi信息
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI openApi() {
return new OpenAPI().info(new Info()
.title("Litchi-Admin接口文档")
.version("v1.0")
.description("此接口文档开发使用，生产环境需配置禁用")
.contact(new Contact()
.url("https://www.gengby.com")
.name("Noah")
.email("gby_dev@163.com")));
}
}
5、在业务接口中使用注解
@Tag(name = "用户管理")
@Validated
@RestController
@RequestMapping("/system/user")
public class UserController {
@Resource
private IUserService userService;
@Resource
private EnumConverter enumConverter;
@Operation(summary = "用户分页列表")
@PostMapping("/page")
public Result<PageResp<UserVO>> page(@Validated @RequestBody UserListQuery userListQuery) {
return ok(userService.page(userListQuery));
}
@Operation(summary = "保存用户")
@PostMapping("/save")
public Result<String> save(@Validated @RequestBody UserSaveCmd userSaveCmd) {
return ok(userService.save(userSaveCmd));
}
@Operation(summary = "修改用户")
@PutMapping("/modify")
public Result<Boolean> modify(@Validated @RequestBody UserModifyCmd userModifyCmd) {
return ok(userService.update(userModifyCmd));
}
@Operation(summary = "删除用户")
@DeleteMapping("/remove")
public Result<Boolean> remove(@NotBlank(message = "ID不能为空") @Parameter(description = "用户ID") @RequestParam String id) {
return ok(userService.delete(Long.parseLong(id)));
}
我们以分页查询参数为例看下代码：
@Data
@Schema(description = "用户查询参数")
@EqualsAndHashCode(callSuper = true)
public class UserListQuery extends PageReq implements Serializable {
@Schema(description = "姓名")
private String userName;
@Schema(description = "手机号")
private String phone;
@Schema(description = "邮箱")
private String email;
@Schema(description = "角色ID")
private String roleId;
}
6、启动项目
访问地址：http://localhost:9999/litchi/doc.html 即刻看到以下页面，你可以看到对应接口的文档描述，也可以在线进行接口调用
欢迎关注我的公众号“程序员洋哥”，原创技术文章第一时间推送。
