目录
2.在application.yml中添加knife4j相关配置
4.在config包下新建Knife4jConfig.java文件
一 .配置依赖基础
1.Spring Boot 3.0中使用knife4j
在pom.xml文件中导入knife4j的依赖(本文springboot的版本是3.3.1)
<!-- Swagger3-knife4j依赖 -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
<version>4.5.0</version>
</dependency>
其实现在就可以使用Knife4j了,暂不做其他配置,启动项目,浏览器输入http://localhost:8080/doc.html查看接口文档
2.在application.yml中添加knife4j相关配置
# knife4j的增强配置,不需要增强可以不配(建议配置一下)
knife4j:
enable: true #开启knife4j,无需添加@EnableKnife4j注解
setting:
language: zh_cn #中文
swagger-model-name: 实体类列表 #重命名SwaggerModel名称,默认
#开启Swagger的Basic认证功能,默认是false
basic:
enable: true
# Basic认证用户名
username: root
# Basic认证密码
password: 123
3.创建config包,在其中新建一个配置类
- 定义配置类WebMvcConfig,实现静态资源映射,将knife4j相关资源放行,保证生成的接口文档能够正常进行展示
package com.example.zhong.config;
//该文件主要进行Knife4j的属性配置,如:作者、版本、接口分组等
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
/**
* <p>
* 配置类,注册web层相关组件
* </p>
*
* @author Patrick
* @since 2024-07-02
*/
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
/**
* 设置静态资源映射
* @param registry
*/
@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.在config包下新建Knife4jConfig.java文件
- 该文件主要进行Knife4j的属性配置,如:作者、版本、接口分组等
package com.example.zhong.config; //配置类WebMvcConfig,实现静态资源映射,将knife4j相关资源放行,保证生成的接口文档能够正常进行展示 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; /** * <p> * Knife4j整合Swagger3 Api接口文档 * </p> * * @author Patrick * @since 2024-07-02 */ @Configuration public class Knife4jConfig { @Bean public GroupedOpenApi adminApi() { // 创建了一个api接口的分组 return GroupedOpenApi.builder() .group("admin-api") // 分组名称 .pathsToMatch("/**") // 接口请求路径规则 .build(); } @Bean public GroupedOpenApi UserApi() { // 创建了一个api接口的分组 return GroupedOpenApi.builder() .group("User-api") // 分组名称 .pathsToMatch("/**") // 接口请求路径规则 .build(); } @Bean public OpenAPI openAPI(){ return new OpenAPI() .info(new Info() // 基本信息配置 .title("xxxApi接口文档") // 标题 .description("xxx接口服务...") // 描述Api接口文档的基本信息 .version("v1.0.0") // 版本 // 设置OpenAPI文档的联系信息,包括联系人姓名为"patrick",邮箱为"patrick@gmail.com"。 .contact(new Contact().name("hhh").email("xxxxxxxxqq.com")) // 设置OpenAPI文档的许可证信息,包括许可证名称为"Apache 2.0",许可证URL为"http://springdoc.org"。 .license(new License().name("Apache 2.0").url("http://springdoc.org")) ); } }
二 .创建测试
1.entity实体类
-
@Schema(description = “ ”): 标记实体类属性
package com.example.zhong.domain; import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; @Data @NoArgsConstructor @AllArgsConstructor @Schema(description = "用户实体") public class User { @Schema(description = "用户名字") public String username; @Schema(description = "用户密码") public String password; }
2.controller控制层
-
@Tag(name = “ ”): 标记接口类别
-
@Operation(summary =“ ”): 标记接口操作
创建(create) – 使用Post方法;
修改(update) – 使用Post方法;
删除(delete) – 使用Delete方法;package com.example.zhong.controller; import com.example.zhong.domain.User; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import lombok.extern.slf4j.Slf4j; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @Slf4j @RestController @RequestMapping("/user") @Tag(name = "用户列表") public class UserController { @GetMapping() @Operation(summary = "用户分页查询") public User getUser(){ return new User(); } }
三 .重启项目并访问接口文档
访问http://localhost:8080/doc.html,可以看到我们配置的属性已经在页面中显示出来了
-