当前位置：首页 > news >正文

swagger基本注解@Tag、@Operation、@Parameters、@Parameter、@ApiResponse、@Schema

news 2025/7/27 11:57:32

swagger基本注解

@Tag

介绍：用于给接口分组，用途类似于为接口文档添加标签。
用于：方法、类、接口。
常用属性：
name：分组的名称
@RestController
@RequestMapping("/sysUser")
@Tag(name = "管理员接口")
public class SysUserController extends BaseController {
@Operation

介绍：用于描述接口的操作。
用于：方法。
常用属性：
summary：操作的摘要信息。
description：操作的详细描述。
   @Operation(summary = "管理员登录", description = "根据账号密码进行管理员登录")//controller层如果介绍的是body 参数  需要使用@RequestBody注解public R<String> login(@RequestBody LoginDTO loginDTO) {return sysUserService.login(loginDTO.getUserAccount(), loginDTO.getPassword());}
@Parameters

介绍：用于指定@Parameter注解对象数组，描述操作的输入参数。
用于：方法。
   @Parameters(value = {@Parameter(name = "userId", in = ParameterIn.PATH, description = "用户ID")})public R<Void> delete(@PathVariable Long userId) {return null;}
@Parameter

介绍：用于描述输入参数。
用于：方法。
常用属性：
name：参数的名称。
in：参数的位置，可以是path、query、header、cookie中的一种。
description：参数的描述。
   @Parameters(value = {@Parameter(name = "userId", in = ParameterIn.PATH, description = "用户ID")})public R<Void> delete(@PathVariable Long userId) {return null;}
@ApiResponse

介绍：用于描述操作的响应结果。
用于：方法。
常用属性：
responseCode：响应的状态码。
description：响应的描述。
    @ApiResponse(responseCode = "1000", description = "操作成功")@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")@ApiResponse(responseCode = "3102", description = "用户不存在")@ApiResponse(responseCode = "3103", description = "用户名或密码错误")//controller层如果介绍的是body 参数  需要使用@RequestBody注解public R<String> login(@RequestBody LoginDTO loginDTO) {return sysUserService.login(loginDTO.getUserAccount(), loginDTO.getPassword());}
@Schema

介绍：用于描述数据模型的属性。
用于：方法、类、接口。
常用属性：
description：响应的描述。
@Getter
@Setter
public class SysUserSaveDTO {@Schema(description = "用户账号")private String userAccount;@Schema(description = "用户密码")private String password;
}