一,前言
在使用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;
}
}
3,启动项目
标记的controller 会展示在左侧
使用到的实体会在展示在 实体列表中
4,调试接口
大功告成,至此,我们对 Knife4j 有了一定的了解和使用,想要了解更多就自己去探索吧!!!