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

用户11288958

发布于 2025-08-11 08:18:26

35300

代码可运行

文章被收录于专栏：学习学习

运行总次数：0

代码可运行

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;
}