springboot3.x入门系列【1】集成knife4j

南宫春水

已于 2024-08-14 08:49:25 修改

阅读量666

点赞数 13

分类专栏： springboot3.x 文章标签： java spring boot

于 2024-08-10 08:00:00 首次发布

本文链接：https://blog.csdn.net/qq_20467517/article/details/141034948

版权

springboot3.x 专栏收录该内容

5 篇文章 0 订阅

订阅专栏

一、简介

在Spring Boot 3.x中集成Knife4j（以前称为Swagger UI增强版）来为API文档提供更友好的界面和管理功能

二、knife4j集成

1.添加knife4j依赖

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

pom.xml

<?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>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.1</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.chopin.uninx</groupId>
    <artifactId>uninx</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>uninx</name>
    <packaging>jar</packaging>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>21</java.version>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.4.0</version>
        </dependency>
        <dependency>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
        </dependency>
        <dependency>
            <groupId>jakarta.validation</groupId>
            <artifactId>jakarta.validation-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <!-- 添加Spring框架核心库 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
        </dependency>

        <!-- 添加Spring框架上下文库 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <arguments>-Dfile.encoding=UTF-8</arguments>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

2. 添加knife4j 配置参数

server:
    port: 8089
    servlet:
        context-path: /uninx
spring:
    profiles:
        active: prod

    application:
        name: uninx
    main:
        allow-circular-references: true
    mvc:
        pathmatch:
            matching-strategy: ant_path_matcher
springdoc:
    #包含主程序和所有子模块的包路径
    show-actuator: true
    swagger-ui:
      path: /swagger-ui.html
      tags-sorter: alpha
      operations-sorter: alpha
    api-docs:
      path: /v3/api-docs
      enable: true
    group-configs:
      - group: 'rayin'
        packages-to-scan: com.rayin
        #paths-to-match: '/**'
# knife4j的增强配置，不需要增强可以不配
knife4j:
    #enable-open-api: true
    #是否开启生产环境屏蔽如果为false则不会启用，文档业务无法访问
    production: false
    #是否启用增强设置
    enable: true
    setting:
      language: zh_cn
      enable-version: true
      enable-swagger-models: true
      swagger-models-name: 用户模块
    basic:
        enable: true
        # Basic认证用户名
        username: rayin
        # Basic认证密码
        password: Abc123++

3. 在接口添加注解声明

TestController.java

package com.rayin.sUpms.business.controller;

import com.github.xiaoymin.knife4j.annotations.ApiSupport;
import com.chopin.sUpms.business.controller.vo.TestVO;
import com.chopin.sUpms.common.enums.CustomErrorCode;
import com.chopin.sUpms.common.exception.CustomeException;
import com.chopin.sUpms.common.response.BaseResponse;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import java.time.LocalDateTime;

/**
 *
 * @describtion
 * @copyright Copyright: 2021-2025
 * @creator 姓名 chopin
 * @create-time 14:45 2024/08/06
 * @modificationHistory=========================逻辑或功能性重大变更记录
 **/
@RestController
@Slf4j
@Tag(name = "这是一个示例接口",description = "测试接口")
@ApiSupport(order = 1)
@RequestMapping("/test")
public class TestController {

    @GetMapping("/get/{id}")
    @Operation(summary = "GET方法测试")
    @Parameters({
            @Parameter(name = "id",description = "主键",in = ParameterIn.QUERY),
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功"),
            @ApiResponse(responseCode = "-1", description = "非200失败")
    })
    public BaseResponse<String> get(@PathVariable String id) {
        return new BaseResponse<>(id);
    }

    @PostMapping("/post")
    @Operation(summary = "POST方法测试",description="这是一个POST方法测试")
    @Parameters({
            @Parameter(name = "id",description = "主键",in = ParameterIn.QUERY),
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "成功"),
            @ApiResponse(responseCode = "-1", description = "非200失败")
    })
    public BaseResponse<TestVO> post(@RequestBody TestVO vo) {
        vo.setId(1).setName("test").setTime(LocalDateTime.now());
        return new BaseResponse<>(vo);
    }

    @GetMapping("/exception")
    @Operation(summary = "错误测试")

    public BaseResponse exception() {
        throw new CustomeException(CustomErrorCode.ERR_TEST);
    }

    @GetMapping("/page")
    @Operation(summary = "返回模板")
    public String page() {
        return "demo";
    }
}

注解说明：

# Controller注解更新
@Api → @Tag
@ApiSort → @ApiSupport

# 类接口注解更新
@ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
@ApiImplicitParam → @Parameter
@ApiImplicitParams → @Parameters
@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

# 实体类注解更新
@ApiModel → @Schema
@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
@ApiModelProperty → @Schema
@ApiParam → @Parameter