目录
一.Swagger快速上手
Swagger是⼀个接⼝⽂档⽣成⼯具，它可以帮助开发者⾃动⽣成接⼝⽂档。当项⽬的接⼝发⽣变更时，Swagger可以实时更新⽂档，确保⽂档的准确性和时效性。Swagger还内置了测试功能，开发者可以直接在⽂档中测试接⼝，⽆需编写额外的测试代码。
使用起来也很简单，直接引入其依赖即可
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.2.0</version>
</dependency>依赖引入后即可进行相应的配置，如下就是一个简单的配置示例，你可以在这个配置项中声明接口文档的名称以及相关的描述，这些描述并不是必须的，可以省略。
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI() {
return new OpenAPI()
.info(new Info()
.title("在线oj系统")
.description("在线oj系统接⼝⽂档")
.version("v1"));
}
}如果你使用的是微服务的架构，为了使该配置项在其他服务中也生效，则需要声明该配置项的位置。即如下图所示在 resource包下声明该配置类的路径。
然后启动项目，访问swagger-ui即可看见当前项目中接口的信息了
同时这些接口中也包含了自动测试的方法，我们点击即可一键进行测试
二.Swagger中的基本注解
为了使该接口文档更丰富，我们可以使用swagger为我们提供的一些基本注解来进行一些自定义的申明，以下是一些常用的注解
@Tag
介绍：⽤于给接⼝分组，⽤途类似于为接⼝⽂档添加标签。
⽤于：⽅法、类、接⼝。
常⽤属性：
name：分组的名称
如下代码，就是使用了@Tag为整个Controller进行了统一的命名分组。
@RestController
@RequestMapping("/sysUser")
@Tag(name = "管理员用户API")
public class SysUserController {
//... ...
}@Operation
介绍：⽤于描述接⼝的操作。
⽤于：⽅法。
常⽤属性：
summary：操作的摘要信息。
description：操作的详细描述。
@Parameters
介绍：⽤于指定@Parameter注解对象数组，描述操作的输⼊参数。
⽤于：⽅法。
@Parameter
介绍：⽤于描述输⼊参数。
⽤于：⽅法。
常⽤属性：
name：参数的名称。
in：参数的位置，可以是 path、query、header、cookie 中的⼀种。
description：参数的描述。
@ApiResponse
介绍：⽤于描述操作的响应结果.
⽤于：⽅法。
常⽤属性：
responseCode：响应的状态码。
description：响应的描述。
就拿下面这个示例来说
- @Operation注解就申明了这个接口是用来查询用户详情的
- @Parameters注解表明了这个接口需要传入的参数，其中@parameter用于修饰每一个参数
- @ApiResponse注解则申明了需要给前端返回怎么样的数据，状态码以及对应的信息
/**
* 根据条件查询管理员用户
*
* @param userId
* @param sex
* @return
*/
@GetMapping("/detail")
@Operation(summary = "⽤⼾详情", description = "根据查询条件查询⽤⼾详情")
@Parameters(value = {
@Parameter(name = "userId", in = ParameterIn.QUERY, description = "⽤⼾ID"),
@Parameter(name = "sex", in = ParameterIn.QUERY, description = "⽤⼾性别")
})
@ApiResponse(responseCode = "1000", description = "成功获取⽤⼾信息")
@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")
@ApiResponse(responseCode = "3101", description = "⽤⼾不存在")
public R<SysUserVO> detail(@RequestParam(required = true) Long userId, @RequestParam(required = false) String sex) {
return null;
}@Schema
介绍：⽤于描述数据模型的属性。
⽤于：⽅法、类、接⼝。
常⽤属性：
description：响应的描述。
如下是个实体类用来封装数据，使用了@Schema注解对字段进行了描述
@Getter
@Setter
public class SysUserVO {
@Schema(description = "用户账号")
private String userAccount;
@Schema(description = "用户昵称")
private String nickName;
}
三.使用Swagger进行测试
Swagger还为我们提供了一个非常使用的功能就是对接口进行一键测试，通过这个功能，我们就不用自己写测试代码了。
我们只需要点击这里的 Try it out 即可一键自测。
然后手动设置传递的参数，之后点击执行Execute即可
在下方也可以看见相应的结果
本次的分享就到此为止了，希望我的分享能给您带来帮助，创作不易也欢迎大家三连支持，你们的点赞就是博主更新最大的动力！
如有不同意见，欢迎评论区积极讨论交流，让我们一起学习进步！
有相关问题也可以私信博主，评论区和私信都会认真查看的，我们下次再见
