官方版本推荐 版本依赖

image.png

spring boot 2.3.12.RELEASE 和 knife4j 2.0.9
  1. 引入依赖 完整的pom.xml文件

    1
    2
    3
    4
    5
    6
    <!-- 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>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    <?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>

  2. 编写配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    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实例
    */
    @Bean
    public 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对象
    }

    }

  3. 测试

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    /*
    * 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;
    }
    }

  4. 测试结果

image.png

spring boot 2.6.13 和 knife4j 3.0.3
  1. 引入依赖

    1
    2
    3
    4
    5
    6
    7
    <!-- 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>

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    <?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>

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

    1
    2
    3
    4
    spring:
    mvc:
    pathmatch:
    matching-strategy: ant_path_matcher
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    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配置实例
    */
    @Bean
    public 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对象
    }

    }

  3. 测试

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    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 {
    @Autowired
    private StudentService studentService;
    //获取所有学生
    @Operation(summary = "查询所有学生信息")
    @GetMapping("list")
    public Result<List<Student>> StudentList(){
    List<Student> list = studentService.list();
    return Result.ok(list);
    }


    }


  4. 测试结果

image.png

spring boot 3 和 knife4j 4.1.0
  1. 引入依赖

    1
    2
    3
    4
    5
    <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.1.0</version>
    </dependency>
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    <?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>

  2. 编写配置文件

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    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 {
    @Bean
    public OpenAPI OpenAPI() {
    return new OpenAPI().info(
    new Info()
    .title("学生信息API")
    .version("1.0")
    .description("学生信息后台管理系统API"));
    }
    @Bean
    public GroupedOpenApi StudentAPI() {

    return GroupedOpenApi.builder().group("学生信息管理").
    pathsToMatch(
    "/student/message/**"
    ).
    build();

    }
    }

  3. 测试

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    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 {
    @Autowired
    private StudentService studentService;

    //获取所有学生
    @Operation(summary = "查询所有学生信息")
    @GetMapping("list")
    public Result<List<Student>> StudentList(){
    List<Student> list = studentService.list();
    return Result.ok(list);
    }

    }


  4. 测试结果

image.png