脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → SpringBoot3集成Swagger3

SpringBoot3集成Swagger3的详细教程

 更新时间：2024年03月08日 10:55:47   作者：洛可可白  
Swagger 3（OpenAPI 3.0）提供了更加强大和灵活的API文档生成能力,本教程将指导您如何在Spring Boot 3项目中集成Swagger3,并使用Knife4j作为UI界面,需要的朋友可以参考下

Swagger是一个用于设计、构建、记录和使用RESTful web服务的开源软件框架。Swagger 3（OpenAPI 3.0）提供了更加强大和灵活的API文档生成能力。本教程将指导您如何在Spring Boot 3项目中集成Swagger3，并使用Knife4j作为UI界面。

1. 添加依赖

首先，您需要在项目的pom.xml文件中添加Swagger3的依赖。同时，为了确保依赖能够正确下载，您可以添加阿里云的Maven镜像仓库。

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


    <repositories>
        <!--阿里云镜像-->
        <repository>
            <id>alimaven</id>
            <name>aliyun maven</name>
            <url>https://maven.aliyun.com/nexus/content/groups/public/</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>

2. 配置Swagger

在Spring Boot项目中创建一个配置类SwaggerConfig，并添加Swagger的配置信息。

import io.swagger.v3.oas.models.ExternalDocumentation;
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.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("标题")
                        .contact(new Contact())
                        .description("我的API文档")
                        .version("v1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("外部文档")
                        .url("https://springshop.wiki.github.org/docs"));
    }
}

3. 实体类和控制层注解

在您的实体类和控制层中使用Swagger注解来描述API。

// 实体类注解示例
import com.alibaba.excel.annotation.ExcelProperty;
import com.alibaba.excel.annotation.write.style.ColumnWidth;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.experimental.Accessors;

import java.util.Date;

@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@Schema(name = "Employee", description = "$!{table.comment}")
public class Emp {
    @ExcelProperty("ID")
    @Schema(description = "ID")
    private int id;
    @ExcelProperty("用户名")
    @Schema(description = "用户名")
    private String names;
    @ExcelProperty("工资")
    @Schema(description = "工资")
    private double salary;
    @ExcelProperty("生日")
    @Schema(description = "生日")
    private Date birthday;
    @ColumnWidth(20)
    @ExcelProperty("头像")
    @Schema(description = "头像")
    private String photo;
    
//    @ColumnWidth(20)
//    @DateTimeFormat("yyyy-MM-dd HH:mm:ss")
//    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
//    @ExcelProperty("创建日期")
//    private Date u_create_time;
}


// 控制层注解示例
import io.swagger.v3.oas.annotations.Operation;

@Operation(summary = "获取所有员工信息")
@GetMapping("/selectAll")
public List<Emp> selectAll() {
    // ...
}

4. 通用返回结果封装

创建一个通用的返回结果类，用于统一API的响应格式。

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Getter;
import lombok.Setter;
import lombok.extern.slf4j.Slf4j;

@Builder(toBuilder = true)
@AllArgsConstructor
@Setter
@Getter
@Slf4j
public class Result<T> {
    /**
     * 提示信息
     */
    @Schema(description = "提示信息")
    private String message;
    /**
     * 是否成功
     */
    @Schema(description = "是否成功")
    private boolean success;
    /**
     * 返回状态码
     */
    @Schema(description = "返回状态码")
    private Integer code;
    /**
     * 数据
     */
    @Schema(description = "数据")
    private T data;

    public Result() {
    }

    public static Result success() {
        Result Result = new Result();
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        Result.setMessage(ResultCode.SUCCESS.getMsg());
        return Result;
    }

    public static Result success(String msg) {
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        return Result;
    }

    public static Result success(Object data) {
        Result Result = new Result();
        Result.setData(data);
        Result.setSuccess(Boolean.TRUE);
        Result.setCode(ResultCode.SUCCESS.getCode());
        Result.setMessage(ResultCode.SUCCESS.getMsg());
        return Result;
    }

    /**
     * 返回失败 消息
     *
     * @return Result
     */
    public static Result failure() {
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(ResultCode.FAILURE.getCode());
        Result.setMessage(ResultCode.FAILURE.getMsg());
        return Result;
    }

    /**
     * 返回失败 消息
     *
     * @param msg 失败信息
     * @return Result
     */
    public static Result failure(String msg) {
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(ResultCode.FAILURE.getCode());
        Result.setMessage(msg);
        return Result;
    }

    public static Result failure(Integer code, String msg) {
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(code);
        Result.setMessage(msg);
        return Result;
    }


    public static Result failure(String msg, ResultCode exceptionCode) {
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        Result.setData(exceptionCode.getMsg());
        return Result;
    }

    /**
     * 返回失败 消息
     *
     * @param exceptionCode 错误信息枚举
     * @return Result
     */
    public static Result failure(ResultCode exceptionCode) {
        Result Result = new Result();
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        Result.setMessage(exceptionCode.getMsg());
        return Result;
    }

    /**
     * 返回失败 消息
     *
     * @param exceptionCode 错误信息枚举
     * @param msg           自定义错误提示信息
     * @return Result
     */
    public static Result failure(ResultCode exceptionCode, String msg) {
        Result Result = new Result();
        Result.setMessage(msg);
        Result.setSuccess(Boolean.FALSE);
        Result.setCode(exceptionCode.getCode());
        return Result;
    }

}

5. 注解说明

Swagger3的注解与Swagger2有所不同，以下是一些常用注解的对照表：

Swagger2注解Swagger3注解注解位置
@Api@Tag(name = “接口类描述”)Controller类上
@ApiOperation@Operation(summary = “接口方法描述”)Controller方法上
@ApiImplicitParams@ParametersController方法上
@ApiImplicitParam@Parameter(description = “参数描述”)Controller方法上
@ApiParam@Parameter(description = “参数描述”)方法参数上
@ApiIgnore@Parameter(hidden = true) 或 @Operation(hidden = true)-
@ApiModel@SchemaDTO类上
@ApiModelProperty@SchemaDTO属性上

6. 访问Swagger UI

启动您的Spring Boot应用后，您可以通过以下地址访问Swagger UI：

http://localhost:8080/doc.html
http://localhost:8080/swagger-ui/index.html

在这里，您可以查看API文档，测试API接口，并获取相关信息。

到此这篇关于SpringBoot3集成Swagger3的详细教程的文章就介绍到这了,更多相关SpringBoot3集成Swagger3内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • Java回调函数与观察者模式实例代码

    Java回调函数与观察者模式实例代码

    这篇文章主要介绍了Java回调函数与观察者模式实例代码，简单介绍了使用观察者模式的场景，分享了相关代码示例，小编觉得还是挺不错的，具有一定借鉴价值，需要的朋友可以参考下
    2018-02-02
  • SpringBoot中的@EnableConfigurationProperties注解原理及用法

    SpringBoot中的@EnableConfigurationProperties注解原理及用法

    在SpringBoot中，@EnableConfigurationProperties注解是一个非常有用的注解，它可以用于启用对特定配置类的支持，在本文中，我们将深入探讨@EnableConfigurationProperties注解，包括它的原理和如何使用,需要的朋友可以参考下
    2023-06-06
  • 深入浅析java web log4j 配置及在web项目中配置Log4j的技巧

    深入浅析java web log4j 配置及在web项目中配置Log4j的技巧

    这篇文章主要介绍了
    2015-11-11
  • Java之NIO基本简介

    Java之NIO基本简介

    这篇文章主要介绍了Java之NIO基本简介,文中给大家讲到了NIO 与 BIO的比较结合实例代码给大家介绍的非常详细，需要的朋友可以参考下
    2023-05-05
  • 关于 Math.random()生成指定范围内的随机数的公式推导问题

    关于 Math.random()生成指定范围内的随机数的公式推导问题

    在 java 中，用于生成随机数的 Math 方法 random()只能生成 0-1 之间的随机数，而对于生成指定区间，例如 a-b 之间的随机数，却只能用相关计算公式，今天通过本文给大家介绍Math.random()生成随机数的公式推导问题，感兴趣的朋友一起看看吧
    2022-09-09
  • 浅谈Java实现回溯算法之八皇后问题

    浅谈Java实现回溯算法之八皇后问题

    八皇后问题是一个古老而又著名的问题，是学习回溯算法的一个经典案例。今天我们就一起来探究一下吧
    2021-06-06
  • Java分布式服务框架Dubbo介绍

    Java分布式服务框架Dubbo介绍

    这篇文章介绍了Java分布式服务框架Dubbo，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧
    2022-06-06
  • Java 中的 File类详情

    Java 中的 File类详情

    这篇文章主要介绍了Java 中的 File类，对于File而言，其封装的并不是一个真正存在的文件，仅仅是一个路径名而已，下面我们来看看文章对File类的详情介绍吧,需要的朋友也可以参考一下
    2021-11-11
  • Java调用windows系统的CMD命令并启动新程序

    Java调用windows系统的CMD命令并启动新程序

    本文教你如何使用java程序调用windows系统的CMD命令启动新程序方法,需要的朋友可以参考下
    2023-05-05
  • Spring boot实现上传文件到本地服务器

    Spring boot实现上传文件到本地服务器

    这篇文章主要为大家详细介绍了Spring boot实现上传文件到本地服务器，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
    2022-08-08

最新评论