已添加Swagger Maven依赖却无法导入@ApiParam或@ApiModel注解

云原生阿岚

2026-9-30

问题根因

你当前引入的是 Swagger 3（OpenAPI 3规范） 的swagger-annotations 2.x版本依赖，@ApiParam、@ApiModel属于Swagger 1.x/2.x版本的旧注解，在Swagger 3中已经被重构重命名，因此无法在现有依赖中找到对应类。

解决方案

无需新增额外依赖，直接使用Swagger 3中对应的等效新注解即可：

原Swagger2的@ApiModel（用于标注接口返回/请求实体类）替换为@Schema，导入语句如下：

import io.swagger.v3.oas.annotations.media.Schema;

原Swagger2的@ApiParam（用于标注接口请求参数）替换为@Parameter，导入语句如下：

import io.swagger.v3.oas.annotations.Parameter;

使用示例

// 实体类标注示例
@Schema(description = "用户登录请求参数")
public class UserLoginReq {
    @Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED, example = "zhangsan")
    private String username;
    @Schema(description = "密码", requiredMode = Schema.RequiredMode.REQUIRED, example = "123456")
    private String password;
}

// 接口参数标注示例
@Operation(summary = "根据用户ID查询用户信息")
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "查询成功"),
        @ApiResponse(responseCode = "404", description = "用户不存在")
})
public UserVO getUserById(@Parameter(description = "用户ID", required = true) @PathVariable Long id) {
    // 业务逻辑实现
}