Springboot3集成Knife4j的步骤以及使用(最完整版)

 更新时间:2024年11月09日 11:29:37   作者:秋风~微凉  
这篇文章主要介绍了Springboot3集成Knife4j的步骤以及使用的相关资料,Knife4j是一种增强Swagger的工具,支持黑色主题和更多配置选项,它与swagger-bootstrap-ui相比,提供了更现代的外观和更多的功能,需要的朋友可以参考下

一,前言

在使用swagger-bootstrap-ui时我觉得它的样式和蓝色主色调不符合我的审美,所以我觉得使用一个更强的工具 Knife4j。Knife4j是一个用于SpringBoot和SpringCloud的增强Swagger的工具,提供黑色主题和更多配置选项。Knife4j在更名之前,原来的名称是叫swagger-bootstrap-ui,这是两种不一样风格的ui显示,将原来的蓝色变成炫酷的黑色模式。

二,Knife4j和swagger-bootstrap-ui对比

工具状态风格配置
Knife4j持久更新黑色主题支持配置文件编写配置项
swagger-bootstrap-ui停更,2.x后更名为Knife4j蓝色主题不支持

三,Spring Boot和Knife4j版本关系 

Spring Boot版本Knife4j Swagger 2规范Knife4j OpenAPI 3规范
1.5.x ~ 2.0.0< Knife4j 2.0.0>= Knife4j 4.0.0
2.0 ~ 2.2Knife4j 2.0.0 ~ 2.0.6>= Knife4j 4.0.0
2.2.x ~ 2.4.0Knife4j 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

详细了解:https://doc.xiaominfo.com/docs/quick-start/start-knife4j-version

注意:

  • Spring Boot 只支持 OpenAPI3 规范
  • Knife4j提供的starter已经引用了springdoc-openapi的jar包,使用时需要避免jar包冲突
  • Springboot3集成Knife4j时需要 JDK版本 >= 17

四,集成步骤

项目环境:

       JDK:17

       SpringBoot:3.0.13

       Knife4j:4.5.0

1,引入依赖

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

启动项目就可以查看界面了

2,在application.yml中添加knife4j相关配置

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    #自定义swagger前端请求路径,输入http:localhost:8080/swagger-ui会自动重定向到swagger页面
    path: /swagger-ui
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs  #swagger后端请求地址
    enabled: true   #是否开启文档功能
  group-configs: #分组配置,可配置多个分组
    - group: 'default'             #分组名称
      paths-to-match: '/**'        #配置需要匹配的路径
      packages-to-scan: com.cms    #配置要扫描包的路径,一般配置到启动类所在的包名
    - group: 'admin-api'
      paths-to-match: '/**'
      packages-to-scan: com.cms

添加knife4j的增强配置

# knife4j的增强配置,不需要增强可以不配
knife4j:
  enable: true    #开启knife4j,无需添加@EnableKnife4j注解
  setting:
    language: zh_cn   #中文
    swagger-model-name: 实体列表   #默认为:Swagger Models
  #开启Swagger的Basic认证功能,默认是false,开启后访问文档页面时会弹出用户名和密码输入框
  basic:
    enable: true
    # Basic认证用户名
    username: user
    # Basic认证密码
    password: 123456

3,定义配置类WebMvcConfig

package com.cms.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * web层配置类,实现静态资源映射,将knife4j相关资源放行,保证生成的接口文档能够正常进行展示
 * @author Hva
 */
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    /**
     * 设置静态资源映射
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 添加静态资源映射规则
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        //配置 knife4j 的静态资源请求映射地址
        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

4,定义Knife4j配置类

package com.cms.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;

/**
 * Knife4j整合Swagger3 Api接口文档配置类
 * @author Hva
 */
@Configuration
public class Knife4jConfig {

    /**
     * 创建了一个api接口的分组
     * 除了配置文件方式创建分组,也可以通过注册bean创建分组
     */
    @Bean
    public GroupedOpenApi adminApi() { 
        return GroupedOpenApi.builder()
                // 分组名称
                .group("app-api")
                // 接口请求路径规则
                .pathsToMatch("/**")
                .build();
    }

    /**
     * 配置基本信息
     */
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        // 标题
                        .title("Knife4j整合Swagger3 Api接口文档")
                        // 描述Api接口文档的基本信息
                        .description("Knife4j后端接口服务...")
                        // 版本
                        .version("v1.0.0")
                        // 设置OpenAPI文档的联系信息,姓名,邮箱。
                        .contact(new Contact().name("Hva").email("Hva@163.com"))
                        // 设置OpenAPI文档的许可证信息,包括许可证名称为"Apache 2.0",许可证URL为"http://springdoc.org"。
                        .license(new License().name("Apache 2.0").url("http://springdoc.org"))
                );
    }
}

重启项目就可以看到自己配置的信息了

五,基本使用

引入下面测试需要的依赖

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus</artifactId>
    <version>3.5.5</version>
</dependency>

1,创建实体类

@Schema(description = ""): 标记实体类属性

package com.cms.entry;

import com.baomidou.mybatisplus.annotation.TableName;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

/**
 * @author Hva
 */
@Data
@TableName("user")
@Schema(description = "用户登录")
public class UserVO {
    
    @Schema(description = "用户名")
    private String username;

    @Schema(description = "用户密码")
    private String password;

}

2,创建controller

@Tag(name = “ ”): 标记 controler 的类别
@Operation(summary =“ ”): 标记接口操作

package com.cms.controller;

import com.cms.entry.UserVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author: Hva
 * @Description: 用户controller
 */
@RestController
@Tag(name = "用户controller")
public class UserController {
    /**
     * 用户列表
     */
    @Operation(summary = "登录接口")
    @PostMapping("/login")
    public UserVO list(
            @RequestBody UserVO userVO
    ) {
       return userVO;
    }
}

3,启动项目

标记的controller 会展示在左侧

使用到的实体会在展示在 实体列表中 

4,调试接口

大功告成,至此,我们对 Knife4j 有了一定的了解和使用,想要了解更多就自己去探索吧!!!

总结

到此这篇关于Springboot3集成Knife4j的步骤以及使用的文章就介绍到这了,更多相关Springboot3集成Knife4j内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • java模拟客户端向服务器上传文件

    java模拟客户端向服务器上传文件

    这篇文章主要为大家详细介绍了java模拟客户端向服务器上传文件,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2019-10-10
  • 使用@PathVariable注解如何实现动态传值

    使用@PathVariable注解如何实现动态传值

    这篇文章主要介绍了使用@PathVariable注解如何实现动态传值,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-10-10
  • Java实现视频时间维度剪切的工具类

    Java实现视频时间维度剪切的工具类

    这篇文章主要为大家详细介绍了将视频按照时间维度进行剪切的Java工具类,文中的示例代码讲解详细,感兴趣的小伙伴可以跟随小编一起了解一下
    2022-12-12
  • Spring发送邮件如何内嵌图片增加附件

    Spring发送邮件如何内嵌图片增加附件

    这篇文章主要介绍了Spring发送邮件如何内嵌图片增加附件,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2020-10-10
  • Java实现表白小程序

    Java实现表白小程序

    本文讲述了Java实现表白的代码实例。具有很好的参考价值,希望对大家有所帮助,一起跟随小编过来看看吧,具体如下:
    2018-05-05
  • SpringMVC Tomcat控制台乱码问题解决方案

    SpringMVC Tomcat控制台乱码问题解决方案

    这篇文章主要介绍了SpringMVC Tomcat控制台乱码问题解决方案,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2020-05-05
  • SpringBoot使用ApplicationEvent&Listener完成业务解耦

    SpringBoot使用ApplicationEvent&Listener完成业务解耦

    这篇文章主要介绍了SpringBoot使用ApplicationEvent&Listener完成业务解耦示例详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-05-05
  • 解决Hmily与Feign冲突报错 NullPointerException的问题

    解决Hmily与Feign冲突报错 NullPointerException的问题

    这篇文章主要介绍了解决Hmily与Feign冲突报错 NullPointerException的问题,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-11-11
  • Spring Cloud灰度部署实现过程详解

    Spring Cloud灰度部署实现过程详解

    这篇文章主要为大家介绍了Spring Cloud灰度部署实现过程详解,有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2023-06-06
  • Java通过反射查看类的信息示例

    Java通过反射查看类的信息示例

    这篇文章主要介绍了Java通过反射查看类的信息,结合实例形式详细分析了java基于反射获取类信息的相关原理与实现技巧,需要的朋友可以参考下
    2019-07-07

最新评论