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

一，前言

在使用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.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

详细了解：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;
    }
}