本教程旨在指导开发者如何在 swagger api 文档中，为请求体（request body）内的参数添加清晰的描述并标记其可选性。我们将重点介绍 `@apimodelproperty` 注解的正确使用方法，包括如何利用其 `value` 属性进行描述以及 `required` 属性来指示参数是否为可选，并明确区分其与 `@apiparam` 注解的不同应用场景，以生成准确、专业的 api 文档。
引言
在现代微服务架构中，API 文档是团队协作和外部集成的关键。Swagger（或 OpenAPI）作为行业标准，能够自动生成交互式 API 文档，极大地提升了开发效率和沟通质量。然而，要生成高质量的文档，正确使用其提供的注解至关重要。本文将聚焦于一个常见场景：如何在 Swagger 文档中，为作为请求体（Request Body）一部分的数据模型参数添加详细描述并明确标记其可选性。
请求体参数的文档化挑战
当我们在 Spring Boot 等框架中定义 RESTful API 时，经常会遇到使用 @RequestBody 注解来接收一个复杂的数据对象作为请求体。这个数据对象通常是一个自定义的 Java 类（DTO），其中包含多个字段。对于这些封装在数据模型中的字段，如何为其添加描述、示例值以及指示其是否为可选参数，是许多开发者面临的疑问。尤其是在面对 @ApiParam 和 @ApiModelProperty 这两个功能相似的注解时，选择正确的注解是确保文档准确性的关键。
@ApiModelProperty：请求体模型参数的正确选择
对于作为请求体一部分的数据模型类（DTO 或实体类）中的字段，正确的注解是 @ApiModelProperty。此注解专门用于修饰数据模型类的属性（字段），使其在 Swagger UI 中正确展示。
1. 描述参数
使用 value 属性来为字段提供详细的描述。这个描述会直接呈现在 Swagger UI 的模型定义和参数详情中。需要注意的是，notes 属性在 Swagger Core 的较新版本中已不再使用，因此应始终使用 value。
2. 标记可选性
通过设置 required = false 可以明确指出该参数是可选的。如果未设置此属性，Swagger 可能会根据字段的类型（例如，原始类型默认必填，引用类型默认可选）或是否存在 @NotNull 等 JSR 303/380 校验注解来推断其必填性。但为了文档的清晰性和准确性，强烈建议显式声明。
示例代码
以下代码演示了如何在 PostUserRequest 数据模型中使用 @ApiModelProperty 来描述字段并标记其可选性：
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;
import lombok.Builder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.http.ResponseEntity;
// 控制器层
@RestController
@RequestMapping("/api")
public class UserController {
@PostMapping(value = "/users")
public ResponseEntity<Object> createUser(@RequestBody PostUserRequest postUserRequest) {
// 业务逻辑处理 postUserRequest
System.out.println("Received user request: " + postUserRequest);
return ResponseEntity.ok("User created successfully");
}
}
// 数据模型层
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class PostUserRequest {
@ApiModelProperty(value = "用户的唯一标识符，例如：'user123'。此字段为必填项。", example = "user123", required = true)
private String userId;
@ApiModelProperty(value = "用户的电话号码，例如：'13800138000'。此字段为可选参数。", example = "13800138000", required = false)
private String phone;
@ApiModelProperty(value = "用户的邮箱地址，例如：'test@example.com'。此字段为可选参数。", example = "test@example.com", required = false)
private String email;
@ApiModelProperty(value = "用户的年龄。此字段为可选参数。", example = "30", required = false)
private Integer age;
}在上述示例中，userId 被标记为必填，而 phone、email 和 age 则被明确标记为可选。example 属性进一步提供了示例值，使得文档更加直观。
@ApiParam 与 @ApiModelProperty 的区分
理解这两个注解的区别对于正确使用它们至关重要：
-
@ApiParam: 主要用于修饰控制器方法中的参数。这些参数可以是：
- 路径变量 (@PathVariable)
- 查询参数 (@RequestParam)
- 请求头 (@RequestHeader)
- 表单参数 (@RequestPart 或 HttpServletRequest 中的参数)
- 整个请求体参数 (@RequestBody) 本身：当 @RequestBody 修饰一个复杂对象时，@ApiParam 可以用于描述整个请求体的用途，但它不能深入到请求体内部的字段进行描述。
示例：
@GetMapping("/users/{id}") public ResponseEntity<Object> getUserById( @ApiParam(value = "要查询的用户ID，此为必填路径参数", required = true) @PathVariable("id") String userId) { // ... return ResponseEntity.ok().build(); } @PostMapping(value = "/products") public ResponseEntity<Object> createProduct( @ApiParam(value = "创建产品请求体，包含产品名称和价格等详细信息") @RequestBody CreateProductRequest request) { // ... return ResponseEntity.ok().build(); } // 注意：CreateProductRequest 内部字段的描述仍需 @ApiModelProperty @ApiModelProperty: 专用于数据模型类（通常是 DTO 或实体类）的字段。这些数据模型类通常作为 @RequestBody 的类型，或者作为响应体（Response Body）的类型。它负责描述这些模型内部的各个属性。
简而言之，@ApiParam 描述的是 API 操作的输入参数，而 @ApiModelProperty 描述的是数据模型的内部结构。
注意事项与最佳实践
- 版本兼容性: 确保您使用的 Swagger/Springfox 版本与注解的行为一致。旧版本可能对 notes 属性有不同的处理。
- value 属性的重要性: 始终使用 value 属性来提供参数描述，避免使用 notes 属性，因为它在许多版本中已被废弃或不再生效。
- 明确 required 状态: 即使 Swagger 的默认行为可能与您的预期一致，也建议显式设置 required = true 或 required = false。这不仅提高了文档的准确性，也增强了代码的可读性。
- 结合 example 属性: 使用 example 属性可以为参数提供示例值，这对于 API 的使用者来说非常有帮助，能让他们更快地理解如何构造请求。
- 文档一致性: 在整个项目中保持 API 文档风格和标准的统一。一致的文档能够提供更好的用户体验。
- 避免冗余: 不要在同一个字段上同时使用 @ApiParam 和 @ApiModelProperty，它们有各自明确的职责范围。
总结
通过本教程，我们深入探讨了如何在 Swagger API 文档中，为请求体内的可选参数添加描述。核心在于正确理解并运用 @ApiModelProperty 注解，利用其 value 属性进行描述，并使用 required = false 明确标记参数的可选性。同时，我们明确区分了 @ApiModelProperty 和 @ApiParam 的使用场景，避免了常见的混淆。遵循这些最佳实践，开发者可以生成更加清晰、准确和专业的 API 文档，从而提升开发效率和协作体验。
