Knife4j快速使用

概述

Knife4j是一个用于生成和展示API文档的工具，同时它还提供了在线调试的功能。

了解：

• Knife4j有多个版本，最新版的Knife4j基于开源项目springdoc-openapi，这个开源项目的核心功能就是根据SpringBoot项目中的代码自动生成符合OpenAPI规范的接口信息。
• OpenAPI规范定义接口文档的内容和格式，其前身是Swagger规范。

与SpringBoot集成

与SpringBoot的集成相对简单，具体操作如下

1. 创建SpringBoot项目

2. 引入Maven 依赖

   Knife4j的依赖如下

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

3. 创建配置类

   创建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. 启动项目

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

基本使用

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

1. 描述实体类

   创建com.atguigu.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注解用于描述作为接口参数或者返回值的实体类的数据结构。

2. 描述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请求参数进行描述

参数打平

默认情况下Knife4j为接口生成的接口文档中实体参数字段糅合在一起，不方便调试，可在application.yml文件中增加如下配置，将参数做打平处理

springdoc:
  default-flat-param-object: true