1. 概述
在实际开发中，接口文档的自动化生成已成为标配，而 Swagger（现为 OpenAPI）是其中最主流的工具之一。本文聚焦两个常被混淆的注解：@ApiParam 和 @ApiModelProperty，帮你理清它们的职责边界，避免踩坑。
✅ 正确使用这两个注解，能显著提升 Swagger UI 的可读性和专业度。
❌ 混用或误用则会导致文档信息错乱，给前端或协作方带来困扰。
我们将通过代码示例和 UI 截图，直观展示它们的差异和正确用法。
2. 核心区别
一句话总结：
@ApiParam用于接口参数，@ApiModelProperty用于模型字段。
更具体地说：
- ✅
@ApiParam：修饰 Controller 方法中的请求参数，比如@RequestParam、@PathVariable等。 - ✅
@ApiModelProperty：修饰 POJO 模型类的字段，比如User类中的firstName。
⚠️ 注意：两者作用域完全不同，别搞混了。
3. @ApiParam：接口参数的元数据控制
@ApiParam 的作用是为 API 接口的输入参数添加描述性信息。Swagger 默认能识别 @RequestParam 等注解，但字段名、描述、示例值等往往不够清晰，这时就需要 @ApiParam 来增强。
它能控制以下信息：
name：参数名（可覆盖）value：参数描述example：示例值required：是否必填type：数据类型（通常可省略，Swagger 会自动推断）
示例代码
@RequestMapping(
method = RequestMethod.POST,
value = "/createUser",
produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiOperation(value = "创建用户",
notes = "该接口用于创建新用户")
public User createUser(
@ApiParam(
name = "firstName",
type = "String",
value = "用户的姓名",
example = "Vatsal",
required = true)
@RequestParam String firstName) {
User user = new User(firstName);
return user;
}
Swagger UI 效果
可以看到，参数的描述、示例值都清晰展示，前端一看就懂。
4. @ApiModelProperty：模型字段的文档定制
当你在接口中返回或接收一个对象时，Swagger 会自动生成该对象的结构定义。但默认字段名可能不够友好，描述缺失。@ApiModelProperty 就是用来解决这个问题的。
它可以控制：
value：字段描述name：字段名（可重命名）dataType：指定数据类型example：示例值hidden：是否在文档中隐藏该字段allowableValues：允许的取值范围（如枚举）
示例代码
public class User {
@ApiModelProperty(
value = "用户的姓名",
name = "firstName",
dataType = "String",
example = "Vatsal")
private String firstName;
// getter/setter 省略
}
Swagger UI 效果
模型字段的描述和示例值都完整展示，极大提升了文档可读性。
5. 总结
| 注解 | 使用位置 | 作用目标 | 典型场景 |
|---|---|---|---|
@ApiParam |
Controller 方法参数 | 接口参数 | @RequestParam, @PathVariable 等 |
@ApiModelProperty |
Model 类字段 | 模型属性 | POJO 中的字段，用于请求体或响应体 |
✅ 正确姿势：
- 参数用
@ApiParam，模型用@ApiModelProperty，泾渭分明。
❌ 常见错误：
- 在模型字段上误用
@ApiParam，结果文档不生效。 - 忽略
example字段，导致前端不知道传什么格式。
所有示例代码均已上传至 GitHub：https://github.com/baeldung/tutorials/tree/master/spring-boot-modules/spring-boot-swagger-2（mock 链接，实际项目中替换为真实地址）