Spring Boot 3项目集成Swagger3教程

最新推荐文章于 2024-06-17 20:10:54 发布
最新推荐文章于 2024-06-17 20:10:54 发布
阅读量6.3k 收藏 29
点赞数 23
文章标签： spring boot 后端 java
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/interest_ing_/article/details/136521887
版权

Spring Boot 3项目集成Swagger3教程

🌟 前言

欢迎来到我的小天地，这里是我记录技术点滴、分享学习心得的地方。📚

🛠️ 技能清单
  • 编程语言：Java、C、C++、Python、Go、
  • 前端技术：Jquery、Vue.js、React、uni-app、Echarts
  • UI设计: Element-ui、Antd、Color-ui
  • 后端技术：Spring Boot、Mybatis-plus、Swagger
  • 移动开发：Android
  • 操作系统：Windows、Linux
  • 开发框架：RuoYi、微信小程序
  • 开发工具：VSCode、IDEA、Eclipse、WebStorm、HbuildX、Navicat、Xshell、Android Studio、Postman
  • 数据库技术：MySQL、Redis、SQL Server
  • 版本控制：Git

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接口，并获取相关信息。

🚀 获取源代码

📌 联系方式

如果您对我们的项目感兴趣，或者有任何技术问题想要探讨，欢迎通过以下方式与我联系。我非常期待与您交流，共同学习，共同进步！

🎉 结语

感谢你的访问，如果你对我的技术文章或项目感兴趣，欢迎通过以上方式与我联系。让我们一起在技术的道路上不断前行！🚀

洛可可白
关注
  • 23
    点赞
  • 踩
  • 29
    收藏
    觉得还不错? 一键收藏
  • 打赏
    打赏
  • 0
    评论
Spring Boot 2.7.5 集成 Swagger 3
11-22
Spring Boot 2.7.5 集成 Swagger 3，用于前后端分离开发，前端需要经常查看后端接口定义，以及接口的响应，所以集成可视化、交互式的 api 文档至关重要。此外还可以测试后端接口。
spring boot 2.6.11+springcloud Swagger3构建微服务项目源码
10-28
spring boot 2.6.11 + spring cloud + Swagger3.0.0 微服务项目源码
【SpringBoot整合系列】SpringBoot3.x整合Swagger
低调做人，低调编码，神码都是浮云
03-26 4729
SpringBoot整合系列：SpirngBoot整3合swagger
Spring Boot 整合 Swagger3（接口文档）
weixin_51509009的博客
05-17 328
由于springboot2.6与swagger3不兼容，还需要在application.properties中添加mvc配置。注意需要在配置文件中添加注解@EnableOpenApi。
SpringBoot3使用Swagger3
最新发布
Q95470的博客
06-17 784
Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具。Swagger3是Swagger的最新版本，它提供了许多新功能和改进。Swagger在SpringBoot3中的引入方法发生了改变,网上大部分还是SpringBoot2的版本。访问http://localhost:9090/swagger-ui/index.html#/其中的9090 改成你项目后端使用的端口，注意不能省略后面的index.html。版本也可以使用新版，Springdoc-OpenAPI。
SpringBoot3整合swagger（springdoc-openapi）
蓝影铁哥的博客
06-01 1万+
SpringBoot3、swagger3、springdoc-openapi、jdk17
Spring Boot 3.x- RESTful API集成SpringDoc&Swagger-UI
laopeng301的专栏
05-09 1万+
系列文章目录 系列文章:Spring Boot 3.x 系列教程 文章目录系列文章目录前言一、快速开始二、Springdoc-openapi模块Spring WebMvc支持Spring WebFlux 支持三、Restful Api服务集成基础配置总结 前言 springdoc-openapi 帮助使用Spring Boot项目自动化API文档的生成。springdoc-openapi的工作原理是在运行时检查应用程序，根据Spring配置、类结构和各种注释推断API语义。 自动生成JSON/YAML和
Springboot项目集成Swagger3.0
weixin_44924882的博客
11-19 4505
Springboot集成Swagger-ui 3.0
Springboot 配置使用Swagger3
热门推荐
泡泡的博客
03-12 2万+
Swagger是一个可以根据你的代码，自动生成接口文档的一个工具，并且可以用作接口测试工具，2022年了，Swagger也要用3.0版本了吧启动项目，访问，注意 Swagger3 和 2 访问的页面有细微差别。
springboot使用swagger 3
张小三的博客
01-17 2533
springboot使用swagger 3准备配置接口配置访问地址注意 准备 spring boot项目创建， 引入mysql驱动 等步骤省略。 maven 配置 <!-- swagger 3 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.
Springboot 集成swagger3
baidu_40926496的博客
07-26 1051
2.swagger 启动配置 3.swagger注解 1）启动类中添加 @EnableOpenApi 注解2）controller 添加 @Api(tags=“接口分类名称”)注解3）接口上添加 @ApiOperation(“接口名称”) 注解3）请求响应参数添加 @Schema(name = “字段名”, description = “字段描述”)启动后的ui界面
swagger2依赖包
06-26
这个“swagger2依赖包”包含了Swagger2实现所需的关键组件，使得开发人员可以自动化生成API的客户端代码，从而简化了与服务端交互的过程。 Swagger-Annotations-1.5.9是Swagger的核心组件之一，它提供了Java注解，...
SpringBoot整合Swagger3生成接口文档过程解析
08-18
在SpringBoot项目中，首先需要在pom文件中引入Swagger3依赖，使用以下依赖项： ```xml <groupId>io.springfox <artifactId>springfox-boot-starter <version>3.0.0 ``` 二、Application上面加入@EnableOpenApi...
Swagger3生成API文档配置（Demo）
08-06
首先，我们需要在Spring Boot项目中引入Swagger3的相关依赖。在`pom.xml`文件中，添加以下依赖： ```xml <groupId>io.springfox <artifactId>springfox-boot-starter <version>3.0.0 ``` 这个依赖包含了Swagger...
springboot - 2.7.3版本 - （三）整合Swagger3
09-22
首先，整合Swagger3需要引入相应的依赖。在SpringBoot的`pom.xml`文件中，添加`springdoc-openapi-ui`和`springdoc-openapi-data-rest`依赖。这两个依赖分别提供了UI界面和数据REST的支持。例如： ```xml ...
swagger生成api相关依赖
05-28
在这个主题中，我们将深入探讨 Swagger 如何帮助开发者生成 API 相关的依赖，以及如何在项目中使用它。 首先，Swagger 的核心组件是 Swagger UI 和 Swagger Core。Swagger UI 是一个基于浏览器的工具，用于展示 API...
SpringBoot 3.x + Swagger3 踩坑实录
qq_47413097的博客
04-20 1187
SpringBoot3.x + Springdoc + Knife4j + JDK17解决异常
SpringBoot3整合Swagger3，访问出现404错误问题（未解决）
TrayLei的博客
02-25 1658
3、访问地址变更，从之前的http://localhost:8080/swagger-ui.html变更为http://localhost:8080/swagger-ui/index.html#/秉承着能用就用新的的理念，在JDK、SpringBoot、SpringCloud版本的兼容性下，选择了Java17、SpringBoot3.0.2整合Swagger3。代码编译一切正常，Swagger的Bean也能加载，到了最后访问前端页面swagger-ui的时候出现404。根据Debug显示是在。
SpringBoot整合Swagger3
IT_WEH_coder的博客
10-25 1830
本文将介绍下API可视化框架Swagger在SpringBoot框架中的整合流程，对Swagger3进行测试的一系列内容。
spring boot 集成swagger3
10-16
好的，关于集成Swagger3，你可以按照以下步骤进行操作： 1. 在pom.xml文件中添加Swagger3的依赖： ```xml <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> ``` 2. 在Spring Boot的启动类上添加`@EnableSwagger2`注解： ```java @SpringBootApplication @EnableSwagger2 public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } ``` 3. 创建Swagger配置类，配置Swagger相关信息： ```java @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot集成Swagger3") .description("Spring Boot集成Swagger3示例") .version("1.0") .build(); } } ``` 4. 启动应用程序，访问`http://localhost:8080/swagger-ui/index.html`即可查看API文档。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

洛可可白

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值