我是洋哥,一个拥有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项目为例,详细介绍集成过程,项目源代码地址传送门:https://gitee.com/litchi365/litchi-admin (给个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 即刻看到以下页面,你可以看到对应接口的文档描述,也可以在线进行接口调用