打造优雅API文档体验-编程知识

打造优雅API文档体验

我是洋哥，一个拥有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: alphaoperations-sorter: alphaapi-docs:path: /v3/api-docsenabled: truegroup-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 {@Beanpublic 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 {@Resourceprivate IUserService userService;@Resourceprivate 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;}