Swagger系列：SpringBoot3.x中使用Knife4j

一、简介
二、版本说明
三、使用
四、效果图

一、简介

官网：https://doc.xiaominfo.com/

Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案

Knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案，前身是 swagger-bootstrap-ui，致力于 springfox-swagger 的增强 UI 实现。knife4j 为了契合微服务的架构发展，由于原来 swagger-bootstrap-ui 采用的是后端 Java 代码 + 前端 UI 混合打包的方式，在微服务架构下显的很臃肿，因此项目正式更名为 knife4j，更名后主要专注的方面如下：

后端 Java 代码以及前端 UI 模块进行了分离，在微服务架构下使用更加灵活
提供专注于 Swagger 的增强解决方案，不同于只是单纯增强前端 UI 部分

二、版本说明

版本	说明
1.0~1.9.6	名称是叫`swagger-bootstrap-ui`,蓝色风格Ui
1.9.6	蓝色皮肤风格,开始更名，增加更多后端模块
2.0~2.0.5	Ui基于Vue2.0+AntdV重写,黑色风格,参考示例，底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9	底层springfox框架版本升级知2.10.5,,仅提供Swagger2规范的适配
3.0~3.0.3	底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本，建议开发者不要使用
4.0~	区分OpenAPI2和Swagger3的Maven坐标artifactId OpenAPI2规范服务端解析框架稳定在springfox2.10.5 OpenAPI3框架服务端解析跟随springdoc项目更新迭代建议开发者使用该版本 ,请参考4.x升级文档

Spring Boot版本兼容性

Spring Boot版本	Knife4j Swagger2规范	Knife4j OpenAPI3规范
1.5.x~2.0.0	<Knife4j 2.0.0	>=Knife4j 4.0.0
2.0~2.2	Knife4j 2.0.0 ~ 2.0.6	>=Knife4j 4.0.0
2.2.x~2.4.0	Knife4j 2.0.6 ~ 2.0.9	>=Knife4j 4.0.0
2.4.0~2.7.x	>=Knife4j 4.0.0	>=Knife4j 4.0.0
>= 3.0	>=Knife4j 4.0.0	>=Knife4j 4.0.0

Swagger2规范和OpenAPI3规范的说明

nife4j版本	Swagger2规范	OpenAPI3规范	说明
1.0~1.9.6	springfox 2.9.2	无	Knife4j的前身，名称为`swagger-bootstrap-ui`
1.9.6~2.0.5	springfox 2.9.2	无
2.0.6~2.0.9	springfox 2.10.5	无
3.0.0~3.0.3	springfox 3.0.3	无	过度版本，建议开发者不要使用
4.0.0~	springfox 2.10.5	>=springdoc-openapi 1.6.9	Swagger2规范稳定使用springfox2.10.5保持不变。开发者应该尽早迁移到OpenAPI3规范上来,请参考4.x升级文档

三、使用

1.引入依赖

xml 复制代码

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

2.编写配置类

java 复制代码

package com.mcode.knife4jdemo.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * ClassName: Knife4jConfig
 * Package: com.mcode.knife4jdemo.config
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Configuration
public class Knife4jConfig {
    @Bean
    public GroupedOpenApi adminApi() {      // 创建了一个api接口的分组
        return GroupedOpenApi.builder()
                .group("admin-api")         // 分组名称
                .pathsToMatch("/admin/**")  // 接口请求路径规则
                .build();
    }
    @Bean
    public OpenAPI openAPI(){
        return new OpenAPI()
                .info(new Info()
                        .title("Knife4j标题")
                        .description("Knife4j说明")
                        .version("v1")
                        .contact(new Contact().name("robin").email("robin@gmail.com"))
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );

    }
}

3.编写User类用作模型

java 复制代码

package com.mcode.knife4jdemo.entity;

import io.swagger.v3.oas.annotations.media.Schema;

/**
 * ClassName: User
 * Package: com.mcode.knife4jdemo.entity
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@Schema(description = "用户实体")
public class User {
    @Schema(description = "用户名称")
    private String userName;
    @Schema(description = "密码")
    private String password;
    @Schema(description = "邮箱")
    private String email;

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


    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }

    public int getAge() {
        return age;
    }

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

    public User() {
    }

    public User(String userName, String password, String email, int age) {
        this.userName = userName;
        this.password = password;
        this.email = email;
        this.age = age;
    }
}

4.编写控制器

java 复制代码

package com.mcode.knife4jdemo.controller;

import com.mcode.knife4jdemo.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

/**
 * ClassName: IndexController
 * Package: com.mcode.knife4jdemo.controller
 * Description:
 *
 * @Author: robin
 * @Version: v1.0
 */
@RestController
@Tag(name = "首页")
@RequestMapping("/admin/index")
public class IndexController {
    @Operation(summary = "获取用户")
    @GetMapping("/getUser")
    public User getUser( @Parameter(name = "userName",description = "用户名称",in = ParameterIn.QUERY)String userName) {
        return new User(userName, "123456", "123@qq.com", 18);
    }
    @Operation(summary = "新增用户")
    @PostMapping("/addUser")
    public Boolean addUser(@RequestBody  User user) {
        return true;
    }
}

SpringDoc注解具体可看：https://www.cnblogs.com/vic-tory/p/17690501.html

四、效果图

首页

控制器