0
0

Spring Boot 3项目集成Swagger3教程

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的配置信息。

importio.swagger.v3.oas.models.ExternalDocumentation;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Contact;importio.swagger.v3.oas.models.info.Info;importio.swagger.v3.oas.models.info.License;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassSwaggerConfig{@BeanpublicOpenAPIspringShopOpenAPI(){returnnewOpenAPI().info(newInfo().title("标题").contact(newContact()).description("我的API文档").version("v1").license(newLicense().name("Apache 2.0").url("http://springdoc.org"))).externalDocs(newExternalDocumentation().description("外部文档").url("https://springshop.wiki.github.org/docs"));}}

3. 实体类和控制层注解

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

// 实体类注解示例importcom.alibaba.excel.annotation.ExcelProperty;importcom.alibaba.excel.annotation.write.style.ColumnWidth;importio.swagger.v3.oas.annotations.media.Schema;importlombok.AllArgsConstructor;importlombok.Builder;importlombok.Data;importlombok.NoArgsConstructor;importlombok.experimental.Accessors;importjava.util.Date;@Data@Builder@NoArgsConstructor@AllArgsConstructor@Accessors(chain =true)@Schema(name ="Employee", description ="$!{table.comment}")publicclassEmp{@ExcelProperty("ID")@Schema(description ="ID")privateint id;@ExcelProperty("用户名")@Schema(description ="用户名")privateString names;@ExcelProperty("工资")@Schema(description ="工资")privatedouble salary;@ExcelProperty("生日")@Schema(description ="生日")privateDate birthday;@ColumnWidth(20)@ExcelProperty("头像")@Schema(description ="头像")privateString photo;//    @ColumnWidth(20)//    @DateTimeFormat("yyyy-MM-dd HH:mm:ss")//    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")//    @ExcelProperty("创建日期")//    private Date u_create_time;}// 控制层注解示例importio.swagger.v3.oas.annotations.Operation;@Operation(summary ="获取所有员工信息")@GetMapping("/selectAll")publicList<Emp>selectAll(){// ...}

4. 通用返回结果封装

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

importio.swagger.v3.oas.annotations.media.Schema;importlombok.AllArgsConstructor;importlombok.Builder;importlombok.Getter;importlombok.Setter;importlombok.extern.slf4j.Slf4j;@Builder(toBuilder =true)@AllArgsConstructor@Setter@Getter@Slf4jpublicclassResult<T>{/**
     * 提示信息
     */@Schema(description ="提示信息")privateString message;/**
     * 是否成功
     */@Schema(description ="是否成功")privateboolean success;/**
     * 返回状态码
     */@Schema(description ="返回状态码")privateInteger code;/**
     * 数据
     */@Schema(description ="数据")privateT data;publicResult(){}publicstaticResultsuccess(){ResultResult=newResult();Result.setSuccess(Boolean.TRUE);Result.setCode(ResultCode.SUCCESS.getCode());Result.setMessage(ResultCode.SUCCESS.getMsg());returnResult;}publicstaticResultsuccess(String msg){ResultResult=newResult();Result.setMessage(msg);Result.setSuccess(Boolean.TRUE);Result.setCode(ResultCode.SUCCESS.getCode());returnResult;}publicstaticResultsuccess(Object data){ResultResult=newResult();Result.setData(data);Result.setSuccess(Boolean.TRUE);Result.setCode(ResultCode.SUCCESS.getCode());Result.setMessage(ResultCode.SUCCESS.getMsg());returnResult;}/**
     * 返回失败 消息
     *
     * @return Result
     */publicstaticResultfailure(){ResultResult=newResult();Result.setSuccess(Boolean.FALSE);Result.setCode(ResultCode.FAILURE.getCode());Result.setMessage(ResultCode.FAILURE.getMsg());returnResult;}/**
     * 返回失败 消息
     *
     * @param msg 失败信息
     * @return Result
     */publicstaticResultfailure(String msg){ResultResult=newResult();Result.setSuccess(Boolean.FALSE);Result.setCode(ResultCode.FAILURE.getCode());Result.setMessage(msg);returnResult;}publicstaticResultfailure(Integer code,String msg){ResultResult=newResult();Result.setSuccess(Boolean.FALSE);Result.setCode(code);Result.setMessage(msg);returnResult;}publicstaticResultfailure(String msg,ResultCode exceptionCode){ResultResult=newResult();Result.setMessage(msg);Result.setSuccess(Boolean.FALSE);Result.setCode(exceptionCode.getCode());Result.setData(exceptionCode.getMsg());returnResult;}/**
     * 返回失败 消息
     *
     * @param exceptionCode 错误信息枚举
     * @return Result
     */publicstaticResultfailure(ResultCode exceptionCode){ResultResult=newResult();Result.setSuccess(Boolean.FALSE);Result.setCode(exceptionCode.getCode());Result.setMessage(exceptionCode.getMsg());returnResult;}/**
     * 返回失败 消息
     *
     * @param exceptionCode 错误信息枚举
     * @param msg           自定义错误提示信息
     * @return Result
     */publicstaticResultfailure(ResultCode exceptionCode,String msg){ResultResult=newResult();Result.setMessage(msg);Result.setSuccess(Boolean.FALSE);Result.setCode(exceptionCode.getCode());returnResult;}}

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

🚀 获取源代码

📌 联系方式

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

🎉 结语

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

标签： spring boot 后端 java
本文转载自: https://blog.csdn.net/interest_ing_/article/details/136521887
版权归原作者 洛可可白 所有， 如有侵权，请联系我们删除。
登录后发布评论

“Spring Boot 3项目集成Swagger3教程”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

机器人技术在安全领域的重要作用

安全学习记录——网络篇（一）

图腾柱PFC：HP1010为您的电动两轮车之旅提供绿色，高效，安全的动力

单元测试数据库回滚问题

这才是单元测试，之前我们都错了

【C语言基础】：字符函数和字符串函数

ChatGPT-Next-Web SSRF漏洞+XSS漏洞复现(CVE-2023-49785)

文章导航