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 部分

二、版本说明

Spring Boot版本兼容性

Swagger2规范和OpenAPI3规范的说明

三、使用

1.引入依赖

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

2.编写配置类

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类用作模型

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.编写控制器

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

四、效果图

首页

控制器