本文旨在提供在swagger api文档中，为spring boot应用中`@requestbody`注解所接收的请求体模型中的可选参数添加清晰描述的教程。我们将重点讲解如何正确使用`@apimodelproperty`注解及其`value`属性，以确保api文档的准确性和可读性，并区分其与`@apiparam`的适用场景。
在开发RESTful API时，清晰、准确的API文档是不可或缺的一部分。Swagger（或OpenAPI）作为行业标准，极大地简化了API文档的生成和维护。特别是在处理包含复杂请求体（通过@RequestBody注解接收）的API时，为请求体内的每个参数提供详细描述，尤其是标记出哪些参数是可选的，对于API的使用者来说至关重要。
理解请求体参数描述的需求
当一个API接口接收一个Java对象作为请求体时，这个对象通常被称为数据传输对象（DTO）或模型。该模型中的字段代表了请求体中的各个参数。为了让API文档清晰地展示这些参数的用途和可选性，我们需要在这些字段上应用特定的Swagger注解。
许多开发者在尝试为@RequestBody模型中的字段添加描述时，可能会遇到以下困惑：
- 应该使用@ApiParam还是@ApiModelProperty？
- 如果使用@ApiModelProperty，是使用value属性还是notes属性来提供描述？
@ApiModelProperty的正确使用
@ApiModelProperty是Swagger专门为模型（Model）属性设计的注解。它允许开发者为POJO（Plain Old Java Object）中的字段提供丰富的元数据，包括描述、示例值、数据类型等。
关键点：
- 使用value属性提供描述： value属性是用于为模型字段提供简洁描述的首选方式。
- notes属性已不推荐使用： 在较新的Swagger版本中，notes属性已不再推荐使用或不生效，其功能已被value属性替代。
以下是如何正确使用@ApiModelProperty为模型字段添加描述的示例：
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class PostUserRequest {
@ApiModelProperty(value = "用户唯一标识符", example = "user123", required = true)
private String userId;
@ApiModelProperty(value = "用户姓名", example = "张三", required = false)
private String userName;
@ApiModelProperty(value = "用户手机号，此参数为可选。", example = "13800001234", required = false)
private String phone; // 标记为可选参数
// @ApiModelProperty(notes = "此属性的notes属性已不推荐使用") // 错误或不生效的用法
// private String email;
}在上述示例中，phone字段被清晰地描述为“用户手机号，此参数为可选。”，并且通过required = false明确地向Swagger UI指示了其可选性。
@ApiParam与@ApiModelProperty的区分
理解@ApiParam和@ApiModelProperty各自的适用场景是避免混淆的关键：
-
@ApiParam： 主要用于描述方法参数。这包括通过URL路径传递的参数（@PathVariable）、查询参数（@RequestParam）、表单数据（@RequestPart或@ModelAttribute），以及一些非请求体的主体参数。例如：
@GetMapping("/users/{id}") public ResponseEntitygetUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) { // ... } @PostMapping("/upload") public ResponseEntity uploadFile(@ApiParam(value = "要上传的文件", required = true) @RequestPart MultipartFile file) { // ... } @ApiModelProperty： 专门用于描述数据模型（POJO）的属性。当你的API接收一个对象作为请求体（@RequestBody）时，这个对象内部的字段就应该使用@ApiModelProperty进行描述。
为什么不能在@RequestBody模型字段上使用@ApiParam？
当你尝试在PostUserRequest类的phone字段上使用@ApiParam时，Swagger通常无法正确解析并将其显示在模型描述中。这是因为@ApiParam的设计初衷是作用于方法签名上的参数，而不是POJO的内部字段。Swagger的解析器会查找@ApiModelProperty来构建模型（Schema）的文档。
实践示例：为可选参数添加描述
结合上述知识，我们来构建一个完整的示例，展示如何在Spring Boot中使用Swagger为@RequestBody中的可选参数添加描述。
1. 请求体模型 PostUserRequest.java：
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel(description = "创建用户请求体模型") // 为整个模型添加描述
public class PostUserRequest {
@ApiModelProperty(value = "用户唯一标识符，必填。", example = "user123", required = true)
private String userId;
@ApiModelProperty(value = "用户姓名，可选。", example = "张三", required = false)
private String userName;
@ApiModelProperty(value = "用户手机号，此参数为可选。如果提供，将用于联系用户。", example = "13800001234", required = false)
private String phone; // 明确标记为可选参数
@ApiModelProperty(value = "用户邮箱地址，可选。", example = "test@example.com", required = false)
private String email;
}2. 控制器方法 UserController.java：
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/v1/users")
@Api(tags = "用户管理") // 为控制器添加标签
public class UserController {
@PostMapping("/")
@ApiOperation(value = "创建新用户", notes = "根据提供的用户信息创建一个新用户。手机号和姓名是可选的。")
public ResponseEntity createUser(@RequestBody PostUserRequest postUserRequest) {
// 实际业务逻辑
System.out.println("Received user creation request: " + postUserRequest);
// 假设创建成功
return ResponseEntity.ok("User created successfully with ID: " + postUserRequest.getUserId());
}
} 3. Swagger UI中的呈现：
当上述代码运行并通过Swagger UI访问时，PostUserRequest模型中的userId、userName、phone和email字段都将带有清晰的描述。userId会被标记为必填，而userName、phone和email则会被标记为可选。phone字段的详细描述“用户手机号，此参数为可选。如果提供，将用于联系用户。”将直接显示在文档中，极大地提升了API的可读性和易用性。
注意事项与最佳实践
- 一致性： 始终在整个项目中保持对@ApiModelProperty的统一使用，避免在模型字段上混用@ApiParam。
- required属性： 结合required = true或required = false来明确参数的必填性，这比仅靠描述文字更直观。
- 描述的清晰度： 确保value属性提供的描述简洁明了，准确传达参数的用途和约束。对于可选参数，可以额外说明其默认行为或不提供时的影响。
- 示例值： 使用example属性提供参数的示例值，可以帮助API使用者更快地理解参数的预期格式和内容。
- 模型描述： 考虑使用@ApiModel(description = "...")为整个请求体模型添加一个概括性的描述，提升整体文档质量。
总结
为Swagger API文档中的@RequestBody可选参数添加描述，是构建高质量API文档的关键一环。通过正确使用@ApiModelProperty注解，并利用其value和required属性，开发者可以有效地为模型字段提供清晰、准确的文档信息。区分@ApiParam和@ApiModelProperty的适用场景，将有助于避免常见的文档生成问题，从而提高API的可发现性和易用性。遵循这些最佳实践，将使你的API文档成为开发者友好的强大工具。
