SpringBoot3使用Swagger3

SpringBoot3使用Swagger3

项目中的后端接口进行简单的前端展示

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 pathspringdoc:swagger-ui:path: /swagger-ui.html

2.或者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配置文件

packagecom.sumo.ipd.config;importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Info;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;@ConfigurationpublicclassSwagger3Config{@BeanpublicOpenAPIspringOpenAPI(){// 访问路径：http://localhost:9090/swagger-ui/index.htmlreturnnewOpenAPI().info(newInfo().title("SpringDoc API").description("SpringDoc Simple Application").version("0.0.1"));}}

Swagger 注解迁移

Swagger2 和 Swagger3 使用的是完全不同的两套注解，所以原本使用 Swagger2 相关注解的代码页需要完全迁移，改为使用 Swagger3 的注解。
Swagger2Swagger3@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 ="用户名称")

使用示例

packagecom.sumo.ipd.controller;importcom.sumo.ipd.annotation.BusLog;importcom.sumo.ipd.entity.Department;importcom.sumo.ipd.entity.User;importcom.sumo.ipd.enums.Sex;importcom.sumo.ipd.enums.UserStatus;importcom.sumo.ipd.service.DepartmentService;importcom.sumo.ipd.service.UserService;importcom.sumo.ipd.utils.ExcelUtil;importcom.sumo.ipd.utils.PwdUtil;importcom.sumo.ipd.vo.LoginToken;importcom.sumo.ipd.vo.R;importio.swagger.v3.oas.annotations.Operation;importio.swagger.v3.oas.annotations.tags.Tag;importjakarta.annotation.Resource;importjakarta.servlet.http.HttpSession;importorg.springframework.web.bind.annotation.*;importorg.springframework.web.multipart.MultipartFile;importjava.util.*;@RestController@RequestMapping("user")@CrossOrigin@Tag(name ="UserController", description ="用户接口")publicclassUserController{@ResourceUserService userService;@ResourceDepartmentService departmentService;/**
     * 用户注册
     *
     * @param registerUser
     * @return
     */@Operation(description ="用户注册")@PostMapping("register")publicRregister(@RequestBodyUser registerUser){if(userService
                .query().eq(User.COL_CERTIFICATENO, registerUser.getCertificateNo()).count()>0){returnR.builder().code(0).message("用户已存在！").build();}else{
            userService.save(registerUser);returnR.builder().code(200).message("注册成功！请等待组织管理员审核...").build();}}}