脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → 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内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • SpringBoot实现自定义事件的方法详解

    SpringBoot实现自定义事件的方法详解

    这篇文章将用实例来和大家介绍一下如何在SpringBoot中自定义事件来使用观察者模式。文中的示例代码讲解详细，对我们学习SpringBoot有一定的帮助，需要的可以参考一下
    2022-06-06
  • Mysql存储java对象实例详解

    Mysql存储java对象实例详解

    这篇文章主要介绍了Mysql存储java对象实例详解的相关资料,需要的朋友可以参考下
    2016-11-11
  • [Java]详解Socket和ServerSocket学习笔记

    [Java]详解Socket和ServerSocket学习笔记

    即时类应用或者即时类的游戏，HTTP协议很多时候无法满足于我们的需求，这会，Socket对于我们来说就非常实用了。本篇文章主要介绍了Socket和ServerSocket，有兴趣的可以了解一下。
    2016-12-12
  • java代码mqtt接收发送消息方式

    java代码mqtt接收发送消息方式

    这篇文章主要介绍了java代码mqtt接收发送消息方式,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2023-09-09
  • Java System.currentTimeMillis()时间的单位转换与计算方式案例详解

    Java System.currentTimeMillis()时间的单位转换与计算方式案例详解

    这篇文章主要介绍了Java System.currentTimeMillis()时间的单位转换与计算方式案例详解,本篇文章通过简要的案例,讲解了该项技术的了解与使用,以下就是详细内容,需要的朋友可以参考下
    2021-08-08
  • maven工程中读取resources中的资源文件

    maven工程中读取resources中的资源文件

    Web项目中应该经常有这样的需求,在maven项目的resources目录下放一些文件,比如一些配置文件,资源文件等,本文主要介绍了maven工程中读取resources中的资源文件,具有一定的参考价值,感兴趣的可以了解一下
    2023-12-12
  • Spring轻松解决循环依赖

    Spring轻松解决循环依赖

    Spring的解决循环依赖是有前置条件的，要解决循环依赖我们首先要了解Spring Bean对象的创建过程和依赖注入的方式。依赖注入方式，我之前的博客有所分享，大家可以在看本篇文章之前进行一下小小的回顾
    2023-04-04
  • Java实战之客户信息管理系统

    Java实战之客户信息管理系统

    这篇文章主要介绍了Java实战之客户信息管理系统,文中有非常详细的代码示例,对正在学习java的小伙伴们有非常好的帮助,需要的朋友可以参考下
    2021-04-04
  • Spring中的异步方法@Async失效的原因详解

    Spring中的异步方法@Async失效的原因详解

    这篇文章主要介绍了Spring中的异步方法@Async失效的原因详解,@Async属于异步注解,@Async放在方法上标识该方法为异步方法,异步是指进程不需要一直等待下去,而是继续执行下面的操作,不管其他进程的状态,需要的朋友可以参考下
    2024-01-01
  • 详解JAVA Stream流

    详解JAVA Stream流

    这篇文章主要介绍了JAVA Stream流的相关资料，文中讲解非常细致，代码帮助大家更好的理解和学习，感兴趣的朋友可以了解下
    2020-07-07

最新评论