Knife4j是什么？可以干什么？

1. Knife4j 的定义

Knife4j 是为 Java MVC 框架集成 Swagger 生成 API 文档的增强解决方案。它的前身是 swagger-bootstrap-ui，取名为 Knife4j 是希望它能像一把匕首一样小巧、轻量，并且功能强悍。其底层是对 Springfox 的封装，使用方式也和 Springfox 一致，只是它对接口文档 UI 进行了优化。

2. 核心功能

2.1 文档说明

Knife4j 根据 Swagger 的规范说明，详细列出了接口文档的说明，包括：

接口地址
类型
请求示例
请求参数
响应示例
响应参数
响应码等信息

这些信息使得对接口的使用情况一目了然。

2.2 自动生成接口文档

Knife4j 能够根据代码中的 Swagger 注解自动生成接口文档，包括接口信息、请求参数、响应参数等，极大地减少了编写接口文档的工作量。

3. Knife4j 的优点

功能强大：Knife4j 功能丰富，提供了丰富的文档展示功能。
易于操作：使用简单，易于上手。
美观的 UI 界面：Knife4j 的 UI 设计美观，使用体验良好。
高度定制化：可以根据项目需求进行高度定制。

4. 快速上手

4.1 添加依赖

要在项目中使用 Knife4j，首先需要在项目的 pom.xml 文件中添加相应的依赖。

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

4.2 配置

接下来，需要对 Knife4j 进行一些基本的配置，以便生成文档。
创建com.later.helloknife4j.config.Knife4jConfiguration，内容如下

@Configuration
public class Knife4jConfiguration {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("hello-knife4j项目API")
                        .version("1.0")
                        .description("hello-knife4j项目的接口文档"));
    }
    
    @Bean
    public GroupedOpenApi userAPI() {
        return GroupedOpenApi.builder().group("用户信息管理").
                pathsToMatch("/user/**").
                build();
    }

    @Bean
    public GroupedOpenApi systemAPI() {
        return GroupedOpenApi.builder().group("产品信息管理").
                pathsToMatch("/product/**").
                build();
    }
}

4.3 启动项目

启动SpringBoot项目，访问http://localhost:8080/doc.html，观察接口文档。

4.4 基本使用

Knife4j的使用也十分简单，我们只需使用几个简单注解，对接口进行描述，Knife4j就能自动生成API文档了。具体操作如下

描述实体类

创建com.later.helloknife4j.entity.User，内容如下

@Data
@Schema(description = "用户信息实体")
public class User {

    @Schema(description = "编号")
    private Long id;

    @Schema(description = "用户姓名")
    private String name;

    @Schema(description = "用户年龄")
    private Integer age;

    @Schema(description = "用户邮箱")
    private String email;
}

@Schema注解用于描述作为接口参数或者返回值的实体类的数据结构。

描述Controller接口

创建com.later.helloknife4j.controller.HelloController，内容如下

@RestController
@RequestMapping("/user")
@Tag(name = "用户信息管理")
public class HelloController {


    @Operation(summary = "根据id获取用户信息")
    @GetMapping("getById")
    public User getUserById(@Parameter(description = "用户id") @RequestParam Long id) {
        User user = new User();
        user.setId(id);
        user.setName("zhangsan");
        user.setAge(11);
        user.setEmail("zhangsan@email.com");
        return user;
    }
}

@Tag注解用于对接口进行分类，相同Tag的接口会放在同一个菜单。

@Operation用于对接口进行描述。

@Parameter用于对HTTP请求参数进行描述

5. Knife4j 的应用场景

API 文档生成：为 RESTful API 生成详细的文档，方便前后端开发人员协作。
API 测试：基于生成的文档进行 API 的测试。
API 分享：将生成的文档分享给其他团队成员或外部合作伙伴。

6. 总结

Knife4j 是一个强大的 API 文档生成工具，它简化了 API 文档的创建过程，并提供了美观易用的文档查看界面。对于使用 Java MVC 框架开发 RESTful API 的团队来说，Knife4j 是一个非常有价值的工具。

Later