打造优雅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: 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 即刻看到以下页面，你可以看到对应接口的文档描述，也可以在线进行接口调用