swagger简单使用学习

注意

一下基于spring-boot 3.0.2版本，该版本不支持springfox-swagger2 2.9.2会报错，无法访问swagger

安装

在pomx文件中添加对应的依赖

 <!-- swagger --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.1.0</version> <!-- 确保使用与 Spring Boot 兼容的最新版本 --></dependency>

新版本不需要配置类，安装好依赖后，启动项目，可以直接访问http://localhost:8080/swagger-ui/index.html

效果图：
在这里插入图片描述

常用语法

修改文档信息

如果需要修改文档信息，则需要使用配置类

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 OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档标题") // 设置 API 文档标题.description("这是 API 文档的描述") // 设置 API 文档描述.version("1.0.0") // API 文档版本.contact(new Contact().name("开发者姓名").email("开发者邮箱").url("开发者个人网站或公司网站")).license(new License().name("Apache 2.0").url("https://springdoc.org"))); // 设置开源协议信息}
}

目录结构
在这里插入图片描述
效果

controller信息配置

controller添加描述信息

修改前
在这里插入图片描述
修改后

@Controller
@RequestMapping("/user")
@Tag(name="用户控制器",description = "处理用户相关操作")
public class UserController {@Autowiredprivate UserService userService;// 根据用户id查询用户信息@Operation(summary = "根据id获取用户",description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(Integer id) {User user = userService.findById(id);return new Result(0, "查询成功", user);}
}

@Tag：用于为整个控制器添加描述信息，可以指定控制器的名称 (name) 和描述 (description)。
@Operation：用于为具体的 API 操作（方法）添加摘要 (summary) 和详细描述 (description)。

入参描述

简单参数

 @Operation(summary = "根据id获取用户",description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return new Result(0, "查询成功", user);}

在这里插入图片描述

复杂对象入参

需要在参数实体类中添加

class UserParam {@Schema(description = "用户的唯一标识符，list集合", example = "[12345]")private List<Integer> idList;
}

在这里插入图片描述

返回值描述

在返回值的实体类中使用@Schema注解

public class Result<T> {@Schema(description = "业务状态码  0-成功  1-失败")private Integer code;//业务状态码  0-成功  1-失败@Schema(description = "提示信息")private String message;//提示信息...
}

在这里插入图片描述
需要注意的是controller接口的返回值要指定具体的实体类，否则swagger里无法显示

正确

 @Operation(summary = "根据id获取用户", description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result<User> findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return Result.success(user);}

错误（不影响代码运行，但是没有具体的返回值）

 @Operation(summary = "根据id获取用户", description = "返回用户信息")@GetMapping("/findById")@ResponseBodypublic Result findById(@Parameter(description = "用户id") Integer id) {User user = userService.findById(id);return Result.success(user);}