Swagger API 文档：正确描述请求体中的可选参数

本教程旨在指导开发者如何在 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