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

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

 为了让SwaggerConfig生效（外部bean让Spring能扫描到）

在oj-common-swagger模块下的 resources 下创建

META-INF.spring包

再创建org.springframework.boot.autoconfigure.AutoConfiguration.imports⽂件

在里面写上路径

com.qyy.swagger.SwaggerConfig;

生成当前接口文档的地址

服务器运行之后，在浏览器输入地址：例如我的地址就是

http://localhost:1208/swagger-ui/index.html