springboot 项目集成 knife4j

官方版本推荐版本依赖

spring boot 2.3.12.RELEASE 和 knife4j 2.0.9

引入依赖完整的pom.xml文件

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version>
</dependency>

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.orchids</groupId><artifactId>demo</artifactId><version>0.0.1-SNAPSHOT</version><name>demo</name><description>demo</description><properties><java.version>1.8</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><spring-boot.version>2.3.12.RELEASE</spring-boot.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><version>8.0.31</version><scope>runtime</scope></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.9</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope><exclusions><exclusion><groupId>org.junit.vintage</groupId><artifactId>junit-vintage-engine</artifactId></exclusion></exclusions></dependency></dependencies><dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>1.8</source><target>1.8</target><encoding>UTF-8</encoding></configuration></plugin><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${spring-boot.version}</version><configuration><mainClass>com.orchids.demos.DemoApplication</mainClass><skip>true</skip></configuration><executions><execution><id>repackage</id><goals><goal>repackage</goal></goals></execution></executions></plugin></plugins></build></project>

编写配置类

package com.orchids.demos.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;import java.util.ArrayList;
import java.util.List;/*** @Author qwh* @Date 2024/6/1 0:10*/
@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {/*** 配置Swagger的Docket Bean，用于定义API的文档信息和扫描的包路径。** @return Docket 返回配置好的Docket实例*/@Beanpublic Docket adminApiConfig(){// 初始化参数列表List<Parameter> pars = new ArrayList<>();// 构建用户token参数ParameterBuilder tokenPar = new ParameterBuilder();tokenPar.name("adminId").description("用户token").defaultValue("1").modelRef(new ModelRef("string")).parameterType("header").required(false).build();// 将token参数添加到参数列表pars.add(tokenPar.build());// 创建Docket实例并配置文档信息、包路径选择器、路径选择器等Docket adminApi = new Docket(DocumentationType.SWAGGER_2).groupName("adminApi").apiInfo(adminApiInfo()).select()//扫描的包.apis(RequestHandlerSelectors.basePackage("com.orchids.demos"))// 选择处理admin路径下的API.paths(PathSelectors.regex("/demo/.*")).build()// 全局操作参数设置.globalOperationParameters(pars);return adminApi;}/*** 构建后台管理系统API的详细信息** @return 返回构建好的ApiInfo对象，包含API文档的标题、描述、版本信息以及联系方式*/private ApiInfo adminApiInfo(){// 使用ApiInfoBuilder构建API信息return new ApiInfoBuilder().title("后台管理系统-API文档") // 设置文档标题.description("本文档描述了尚上优选后台系统服务接口定义") // 设置文档描述.version("1.0") // 设置文档版本号.contact(new Contact("username", "http://username.com", "username@gmail.com")) // 设置联系人信息.build(); // 构建并返回ApiInfo对象}}

测试

/** Copyright 2013-2018 the original author or authors.** Licensed under the Apache License, Version 2.0 (the "License");* you may not use this file except in compliance with the License.* You may obtain a copy of the License at**      https://www.apache.org/licenses/LICENSE-2.0** Unless required by applicable law or agreed to in writing, software* distributed under the License is distributed on an "AS IS" BASIS,* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.* See the License for the specific language governing permissions and* limitations under the License.*/package com.orchids.demos.web;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;/*** @author <a href="mailto:chenxilzx1@gmail.com">theonefx</a>*/
@Api(tags = "用户管理")
@RestController
@RequestMapping("/demo")
public class BasicController {// http://127.0.0.1:8080/hello?name=lisi@ResponseBody@GetMapping("/hello")@ApiOperation(value = "测试1")public String hello(@RequestParam(name = "name", defaultValue = "unknown user") String name) {return "Hello " + name;}
}

测试结果

spring boot 2.6.13 和 knife4j 3.0.3

引入依赖

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version>
</dependency>

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.orchids</groupId><artifactId>mybatis</artifactId><version>0.0.1-SNAPSHOT</version><name>mybatis</name><description>mybatis</description><properties><java.version>1.8</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><spring-boot.version>2.6.13</spring-boot.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-boot-starter</artifactId><version>3.5.1</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version></dependency></dependencies><dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>1.8</source><target>1.8</target><encoding>UTF-8</encoding></configuration></plugin><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${spring-boot.version}</version><configuration><mainClass>com.orchids.mybatis.MybatisApplication</mainClass><skip>true</skip></configuration><executions><execution><id>repackage</id><goals><goal>repackage</goal></goals></execution></executions></plugin></plugins></build></project>

编写配置类注意 yml文件需要添加

spring:mvc:pathmatch:matching-strategy: ant_path_matcher

package com.orchids.mybatis.web.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @Author qwh* @Date 2024/5/31 16:58*/
@Configuration
@EnableSwagger2
public class Knife4jConfig {/*** 配置Swagger的Docket Bean。** @return Docket配置实例*/@Beanpublic Docket webApiConfig(){// 创建Docket实例Docket webApi = new Docket(DocumentationType.SWAGGER_2).groupName("StudentApi").apiInfo(webApiInfo()).select()// 选择需要文档化的API，只显示指定包下的页面.apis(RequestHandlerSelectors.basePackage("com.orchids.mybatis"))// 指定路径匹配规则，只对/student开头的路径进行文档化.paths(PathSelectors.regex("/student/.*")).build();return webApi;}/*** 构建API信息* 本函数用于创建并返回一个ApiInfo对象，该对象包含了API文档的标题、描述、版本以及联系方式等信息。** @return 返回构建好的ApiInfo对象*/private ApiInfo webApiInfo(){// 使用ApiInfoBuilder构建API信息return new ApiInfoBuilder().title("Student message API文档") // 设置文档标题.description("本文档描述了Swagger2测试接口定义") // 设置文档描述.version("1.0") // 设置文档版本号.contact(new Contact("nullpointer", "http://blog.nullpointer.love", "nullpointer2024@gmail.com")) // 设置联系人信息.build(); // 构建并返回ApiInfo对象}}

测试

package com.orchids.mybatis.web.controller;import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.orchids.mybatis.model.entity.Student;
import com.orchids.mybatis.model.enums.Sex;
import com.orchids.mybatis.model.enums.Status;
import com.orchids.mybatis.model.result.Result;
import com.orchids.mybatis.web.service.StudentService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;/*** @Author qwh* @Date 2024/5/31 16:50*/
import java.util.List;/*** @Author qwh* @Date 2024/5/31 0:22*/
@Tag(name = "学生信息管理")
@RestController
@RequestMapping("/student/message")
public class StudentController {@Autowiredprivate StudentService studentService;//获取所有学生@Operation(summary = "查询所有学生信息")@GetMapping("list")public Result<List<Student>> StudentList(){List<Student> list = studentService.list();return Result.ok(list);}}

测试结果

spring boot 3 和 knife4j 4.1.0

引入依赖

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

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>com.orchids</groupId><artifactId>springmybatisplus</artifactId><version>0.0.1-SNAPSHOT</version><name>springmybatisplus</name><description>springmybatisplus</description><properties><java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><spring-boot.version>3.0.2</spring-boot.version><knife4j.version>4.1.0</knife4j.version><mybatis-plus.version>3.5.6</mybatis-plus.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>${knife4j.version}</version></dependency><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-boot-starter</artifactId><version>${mybatis-plus.version}</version></dependency></dependencies><dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
</project>

编写配置文件

package com.orchids.springmybatisplus.web.custom.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** @Author qwh* @Date 2024/5/31 21:25*/
@Configuration
public class knife4jConfiguration {@Beanpublic OpenAPI OpenAPI() {return new OpenAPI().info(new Info().title("学生信息API").version("1.0").description("学生信息后台管理系统API"));}@Beanpublic GroupedOpenApi StudentAPI() {return GroupedOpenApi.builder().group("学生信息管理").pathsToMatch("/student/message/**").build();}
}

测试

package com.orchids.springmybatisplus.web.controller;import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.orchids.mybatis.model.result.Result;
import com.orchids.springmybatisplus.model.entity.Student;
import com.orchids.springmybatisplus.model.enums.Sex;
import com.orchids.springmybatisplus.model.enums.Status;
import com.orchids.springmybatisplus.web.service.StudentService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;/*** @Author qwh* @Date 2024/5/31 16:50*/
import java.util.List;/*** @Author qwh* @Date 2024/5/31 0:22*/
@Tag(name = "学生信息管理")
@RestController
@RequestMapping("/student/message")
public class StudentController {@Autowiredprivate StudentService studentService;//获取所有学生@Operation(summary = "查询所有学生信息")@GetMapping("list")public Result<List<Student>> StudentList(){List<Student> list = studentService.list();return Result.ok(list);}}