Spring Boot 3項(xiàng)目集成Swagger3教程

?? 前言

歡迎來(lái)到我的小天地，這里是我記錄技術(shù)點(diǎn)滴、分享學(xué)習(xí)心得的地方。??

?? 技能清單

• 編程語(yǔ)言：Java、C、C++、Python、Go、
• 前端技術(shù)：Jquery、Vue.js、React、uni-app、Echarts
• UI設(shè)計(jì): Element-ui、Antd、Color-ui
• 后端技術(shù)：Spring Boot、Mybatis-plus、Swagger
• 移動(dòng)開(kāi)發(fā)：Android
• 操作系統(tǒng)：Windows、Linux
• 開(kāi)發(fā)框架：RuoYi、微信小程序
• 開(kāi)發(fā)工具：VSCode、IDEA、Eclipse、WebStorm、HbuildX、Navicat、Xshell、Android Studio、Postman
• 數(shù)據(jù)庫(kù)技術(shù)：MySQL、Redis、SQL Server
• 版本控制：Git

Swagger是一個(gè)用于設(shè)計(jì)、構(gòu)建、記錄和使用RESTful web服務(wù)的開(kāi)源軟件框架。Swagger 3（OpenAPI 3.0）提供了更加強(qiáng)大和靈活的API文檔生成能力。本教程將指導(dǎo)您如何在Spring Boot 3項(xiàng)目中集成Swagger3，并使用Knife4j作為UI界面。

1. 添加依賴

首先，您需要在項(xiàng)目的pom.xml文件中添加Swagger3的依賴。同時(shí)，為了確保依賴能夠正確下載，您可以添加阿里云的Maven鏡像倉(cāng)庫(kù)。

        <!--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項(xiàng)目中創(chuàng)建一個(gè)配置類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 {@Beanpublic OpenAPI springShopOpenAPI() {return new OpenAPI().info(new Info().title("標(biāo)題").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. 實(shí)體類和控制層注解

在您的實(shí)體類和控制層中使用Swagger注解來(lái)描述API。

// 實(shí)體類注解示例
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("創(chuàng)建日期")
//    private Date u_create_time;
}// 控制層注解示例
import io.swagger.v3.oas.annotations.Operation;@Operation(summary = "獲取所有員工信息")
@GetMapping("/selectAll")
public List<Emp> selectAll() {// ...
}

4. 通用返回結(jié)果封裝

創(chuàng)建一個(gè)通用的返回結(jié)果類，用于統(tǒng)一API的響應(yīng)格式。

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;/*** 返回狀態(tài)碼*/@Schema(description = "返回狀態(tài)碼")private Integer code;/*** 數(shù)據(jù)*/@Schema(description = "數(shù)據(jù)")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 錯(cuò)誤信息枚舉* @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 錯(cuò)誤信息枚舉* @param msg           自定義錯(cuò)誤提示信息* @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. 注解說(shuō)明

Swagger3的注解與Swagger2有所不同，以下是一些常用注解的對(duì)照表：

Swagger2注解

Swagger3注解

注解位置

@Api

@Tag(name = “接口類描述”)

Controller類上

@ApiOperation

@Operation(summary = “接口方法描述”)

Controller方法上

@ApiImplicitParams

@Parameters

Controller方法上

@ApiImplicitParam

@Parameter(description = “參數(shù)描述”)

Controller方法上

@ApiParam

@Parameter(description = “參數(shù)描述”)

方法參數(shù)上

@ApiIgnore

@Parameter(hidden = true) 或 @Operation(hidden = true)

-

@ApiModel

@Schema

DTO類上

@ApiModelProperty

@Schema

DTO屬性上

6. 訪問(wèn)Swagger UI

啟動(dòng)您的Spring Boot應(yīng)用后，您可以通過(guò)以下地址訪問(wèn)Swagger UI：

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

在這里，您可以查看API文檔，測(cè)試API接口，并獲取相關(guān)信息。

?? 獲取源代碼

• 后端案例：https://gitee.com/bestwishes0203/Front-end-example
• 前端案例：https://gitee.com/bestwishes0203/Back-end-example

---

?? 聯(lián)系方式

如果您對(duì)我們的項(xiàng)目感興趣，或者有任何技術(shù)問(wèn)題想要探討，歡迎通過(guò)以下方式與我聯(lián)系。我非常期待與您交流，共同學(xué)習(xí)，共同進(jìn)步！

• 郵箱：2109664977@qq.com
• Gitee：https://gitee.com/bestwishes0203
• GitHub：https://github.com/bestwishes0203
• CSDN：https://blog.csdn.net/interest_ing_/
• 個(gè)人博客：訪問(wèn)我的博客

---

?? 結(jié)語(yǔ)

感謝你的訪問(wèn)，如果你對(duì)我的技術(shù)文章或項(xiàng)目感興趣，歡迎通過(guò)以上方式與我聯(lián)系。讓我們一起在技術(shù)的道路上不斷前行！??