springboot 项目集成 knife4j

最新推荐文章于 2024-06-22 18:15:40 发布

一橘Java小菜鸟

最新推荐文章于 2024-06-22 18:15:40 发布

阅读量1.6k

点赞数 36

文章标签： spring boot 后端 java

本文链接：https://blog.csdn.net/qq_62383709/article/details/139363850

版权

官方版本推荐版本依赖

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实例
     */
    @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对象
    }

}

测试

/*
 * 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配置实例
     */
    @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对象
    }

}

测试

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);
    }


}

测试结果

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 {
    @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();

    }
}

测试

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);
    }

}