SpringBoot3使用Swagger3的示例详解
作者：夜澜听雨声
本文介绍了如何在Spring Boot 3项目中使用Swagger3进行后端接口的前端展示,首先,通过添加依赖并配置application.yml文件来快速启动Swagger,然后,详细介绍了Swagger3的新注解与Swagger2的区别,并提供了一些常用注解的使用示例,感兴趣的朋友跟随小编一起看看吧
项目中的后端接口进行简单的前端展示
Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具。Swagger3是Swagger的最新版本，它提供了许多新功能和改进。
Swagger在SpringBoot3中的引入方法发生了改变,网上大部分还是SpringBoot2的版本
springboot版本3.2.4
一、依赖引入
用maven构建一个SpringBoot3的项目,在依赖中引入,在pom.xml中添加
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.0.4</version>
</dependency>版本也可以使用新版，Springdoc-OpenAPI网站链接
二、快速启动
1.在application.yml中配置
# swagger-ui custom path
springdoc:
swagger-ui:
path : /swagger-ui.html2.或者properties文件,则配置
代码如下（示例）：
# swagger-ui custom path springdoc.swagger-ui.path=/swagger-ui.html
3.启动项目访问swagger
访问http://localhost:9090/swagger-ui/index.html#/
其中的9090 改成你项目后端使用的端口，注意不能省略后面的index.html
三、使用注解标注接口
Swagger配置文件
package com.sumo.ipd.config;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class Swagger3Config {
@Bean
public OpenAPI springOpenAPI() {
// 访问路径：http://localhost:9090/swagger-ui/index.html
return new OpenAPI().info(new Info()
.title("SpringDoc API")
.description("SpringDoc Simple Application")
.version("0.0.1"));
}
}Swagger 注解迁移
Swagger2 和 Swagger3 使用的是完全不同的两套注解，所以原本使用 Swagger2 相关注解的代码页需要完全迁移，改为使用 Swagger3 的注解。
| Swagger2 | Swagger3 |
|---|---|
| @Api | @Tag |
| @ApiOperation | @Operation |
| @ApiImplicitParams | @Parameters |
| @ApiImplicitParam | @Parameter |
| @ApiModel | @Schema |
| @ApiModelProperty | @Schema |
| @ApiResponses | @ApiResponses |
| @ApiResponse | @ApiResponse |
| @ApiIgnore | @Hidden 或者 其他注解的 hidden = true 属性 |
举例五种常用
@Api
Swagger2 代码
@Api(value = "用户接口", tags = "UserController")
Swagger3 代码
@Tag(name = "UserController", description = "用户接口")
@ApiOperation
Swagger2 代码
@ApiOperation(value = "查询用户数据")
Swagger3 代码
@Operation(description = "查询用户数据")
@ApiImplicitParam
Swagger2 代码
@ApiImplicitParams({
@ApiImplicitParam(name = "currentPage", value = "当前页码", dataTypeClass = Integer.class, required = true),
@ApiImplicitParam(name = "size", value = "当前页大小", defaultValue = "10", dataTypeClass = Integer.class),
@ApiImplicitParam(name = "queryUser", value = "用户查询条件", dataTypeClass = User.class)
})Swagger3 代码
@Parameters({
@Parameter(name = "currentPage", description = "当前页码", required = true),
@Parameter(name = "size", description = "当前页大小", example = "10"),
@Parameter(name = "queryUser", description = "用户查询条件")
})@ApiModel
Swagger2 代码
@ApiModel(value = "用户信息实体类")
Swagger3 代码
@Schema(name = "用户信息实体类")
@ApiModelProperty
Swagger2 代码
@ApiModelProperty(value = "用户名称")
Swagger3 代码
@Schema(name = "用户名称")
使用示例
package com.sumo.ipd.controller;
import com.sumo.ipd.annotation.BusLog;
import com.sumo.ipd.entity.Department;
import com.sumo.ipd.entity.User;
import com.sumo.ipd.enums.Sex;
import com.sumo.ipd.enums.UserStatus;
import com.sumo.ipd.service.DepartmentService;
import com.sumo.ipd.service.UserService;
import com.sumo.ipd.utils.ExcelUtil;
import com.sumo.ipd.utils.PwdUtil;
import com.sumo.ipd.vo.LoginToken;
import com.sumo.ipd.vo.R;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import jakarta.servlet.http.HttpSession;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.util.*;
@RestController
@RequestMapping("user")
@CrossOrigin
@Tag(name = "UserController", description = "用户接口")
public class UserController {
@Resource
UserService userService;
@Resource
DepartmentService departmentService;
/**
* 用户注册
*
* @param registerUser
* @return
*/
@Operation(description = "用户注册")
@PostMapping("register")
public R register(@RequestBody User registerUser) {
if (userService
.query()
.eq(User.COL_CERTIFICATENO, registerUser.getCertificateNo())
.count() > 0) {
return R.builder().code(0).message("用户已存在！").build();
} else {
userService.save(registerUser);
return R.builder().code(200).message("注册成功！请等待组织管理员审核...").build();
}
}
}到此这篇关于SpringBoot3使用Swagger3的文章就介绍到这了,更多相关SpringBoot3使用Swagger3内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！