Knife4j-openapi3简单使用（通俗易懂版）

---

前言

这是本人自己第一次写的博客，如果有错误或者不规范的地方请指出来，一起加油，感谢大家观看！！！

---

一、knife4j是什么？

Knife4j是一个用于生成和展示API文档的工具，同时它还提供了在线调试的功能,前身是swagger-bootstrap-ui,小巧,轻量,并且功能强悍!

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

---

二、knife4j-openapi3常用注解

通过注解可以控制生成的接口文档，使接口文档拥有更好的可读性，常用注解如下：

注解	说明
@Tag	用于说明或定义的标签
@Operation	用在类上,描述API操作的元数据信息，例如Controller，表示对类的说明
@Schema	用于描述实体类属性的描述、示例、验证规则等，比如POJO类及属性
@Parameter	加粗样式用于描述 API 操作中的参数,对HTTP请求参数进行描述

---

注解描述和常用参数我都在下面的代码和照片中展示出来了

三、SpringBoot整合knife4j-openapi3

1.创建一个Springboot项目并引入依赖

为了更简单一下，我这里就引用两个依赖（我用的jdk17）

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>3.1.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>
    </dependencies>

2.config配置类

package com.guozi.config;


import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableKnife4j
public class Knife4jConfig  {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("knife4j-openapi3入门测试")
                        .version("1.0")
                        .description("knife4j-openapi3项目的接口文档"));
    }

    @Bean
    public GroupedOpenApi userAPI() {
        return GroupedOpenApi.builder().group("用户信息管理").
                pathsToMatch("/user/**").
                build();
    }

    @Bean
    public GroupedOpenApi systemAPI() {
        return GroupedOpenApi.builder().group("水果信息管理").
                pathsToMatch("/fruit/**").
                build();
    }
}

3.测试实体类

fruit类

package com.guozi.entity;
import io.swagger.v3.oas.annotations.media.Schema;
@Schema(description = "水果实体类")
public class Fruit {
    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Schema(description = "id")
    private Integer id;

    @Schema(description = "水果名称")
    private String name;
}

user类

package com.guozi.entity;
import io.swagger.v3.oas.annotations.media.Schema;
@Schema(description = "用户信息实体")
public class User {
    @Schema(description = "id")
    private Integer id;
    public Integer getId() {
        return id;
    }
    public void setId(Integer id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

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

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


}

4.控制类

FruitController

package com.guozi.controller;

import com.guozi.entity.Fruit;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/fruit")
@Tag(name = "`112")
public class FruitController {

    @Operation(summary = "根据id获得水果信息")
    @GetMapping("getById")
    public Fruit getFruitById(@Parameter(description = "水果id") @RequestParam Integer id){
        Fruit fruit = new Fruit();
        fruit.setId(id);
        fruit.setName("苹果");
        return fruit;
    }

    @Operation(summary = "获得水果信息")
    @GetMapping("getFruit")
    public Fruit getFruit(@Parameter(description = "水果id") @RequestParam String name){
        Fruit fruit = new Fruit();
        fruit.setId(1);
        fruit.setName(name);
        return fruit;
    }
}

UserController

package com.guozi.controller;


import com.guozi.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

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

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

    @Operation(summary = "根据名字获取用户信息")
    @GetMapping("getByName")
    public User getUserByName(@Parameter(description = "用户名字") @RequestParam String name) {
        User user = new User();
        user.setId(1);
        user.setName(name);
        user.setAge(11);
        return user;
    }
}

5.启动

访问http://localhost:8080/doc.html

可以调试一下

访问正确成功！！！

四、注意

Spring Boot 3 只支持OpenAPI3规范
Knife4j提供的starter已经引用springdoc-openapi的jar，开发者需注意避免jar包冲突
JDK版本必须 >= 17