SpringBoot3集成Swagger3的詳細(xì)教程
更新時(shí)間：2024年03月08日 10:55:47 作者：洛可可白
Swagger 3（OpenAPI 3.0）提供了更加強(qiáng)大和靈活的API文檔生成能力,本教程將指導(dǎo)您如何在Spring Boot 3項(xiàng)目中集成Swagger3,并使用Knife4j作為UI界面,需要的朋友可以參考下
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. 添加依賴(lài)
首先，您需要在項(xiàng)目的pom.xml文件中添加Swagger3的依賴(lài)。同時(shí)，為了確保依賴(lài)能夠正確下載，您可以添加阿里云的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è)配置類(lèi)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("標(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í)體類(lèi)和控制層注解
在您的實(shí)體類(lèi)和控制層中使用Swagger注解來(lái)描述API。
// 實(shí)體類(lèi)注解示例
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é)果類(lèi)，用于統(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 = “接口類(lèi)描述”) | Controller類(lèi)上 |
| @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類(lèi)上 |
| @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)信息。
到此這篇關(guān)于SpringBoot3集成Swagger3的詳細(xì)教程的文章就介紹到這了,更多相關(guān)SpringBoot3集成Swagger3內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
Java實(shí)現(xiàn)AES加密算法的簡(jiǎn)單示例分享
這篇文章主要介紹了Java實(shí)現(xiàn)AES加密算法的簡(jiǎn)單示例分享,AES算法是基于對(duì)密碼值的置換和替代,需要的朋友可以參考下2016-04-04
java實(shí)現(xiàn)簡(jiǎn)單的加減乘除計(jì)算器
這篇文章主要為大家詳細(xì)介紹了java實(shí)現(xiàn)簡(jiǎn)單的加減乘除計(jì)算器，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2021-09-09
重學(xué)SpringBoot3之日志Logging使用方式
在日常開(kāi)發(fā)中會(huì)遇到不同的異常,日志方便我們?nèi)ヅ挪樘幚?這篇文章主要給大家介紹了關(guān)于重學(xué)SpringBoot3之日志Logging使用方式的相關(guān)資料,文中通過(guò)代碼介紹的非常詳細(xì),需要的朋友可以參考下2024-06-06
大家好，本篇文章主要講的是JAVA用for循環(huán)打印空心菱形，感興趣的同學(xué)趕快來(lái)看一看吧，對(duì)你有幫助的話記得收藏一下2022-01-01
Java接口測(cè)試框架Restassured介紹及常用方法
Java接口測(cè)試主要用于驗(yàn)證Java應(yīng)用程序中不同模塊或服務(wù)之間的交互是否符合預(yù)期,這篇文章主要介紹了Java接口測(cè)試框架Restassured介紹及常用方法的相關(guān)資料,文中通過(guò)代碼介紹的非常詳細(xì),需要的朋友可以參考下2026-03-03
Spring?Data?JPA?映射VO/DTO對(duì)象方式
這篇文章主要介紹了Spring?Data?JPA?映射VO/DTO對(duì)象方式，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2021-11-11
這篇文章主要為大家詳細(xì)介紹了pagehelper分頁(yè)工具類(lèi)的封裝，文中示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2022-08-08
一文系統(tǒng)梳理Java中字符串比較的高頻誤區(qū)
本文圍繞?Java?字符串比較中的高頻誤區(qū)展開(kāi),系統(tǒng)梳理?==、equals()、字符串常量池、new?String()、編譯期與運(yùn)行期拼接、final?常量折疊以及?intern()?的核心規(guī)則,希望幫助?Java?初學(xué)者真正理解?String?比較背后的引用關(guān)系與常見(jiàn)踩坑點(diǎn)2026-05-05
這篇文章主要介紹了Spring MVC處理方法返回值過(guò)程解析,文中通過(guò)示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下2020-02-02
這篇文章主要為大家詳細(xì)介紹了struts2實(shí)現(xiàn)多文件上傳，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2018-08-08