Swagger文档参数校验标注实战技巧

在开发接口时，光写清楚接口功能还不够，ref="/tag/419/" style="color:#2B406D;font-weight:bold;">参数怎么填、哪些必传、格式要求是什么，都得让调用者一目了然。Swagger 就是干这个的——它能自动生成接口文档，但默认展示的信息太基础。这时候就得靠参数校验标注，把规则清清楚楚标出来。

为什么要加参数校验标注？

想象一下你同事第一次调你的用户注册接口，看到一堆字段：username、email、password……他哪知道哪个不能空？密码要几位？邮箱格式有没有限制？如果文档里没写，就得翻代码或者挨个试错。加上校验标注后，Swagger 页面上直接显示“此字段必填”“最小长度8位”，沟通成本立马下降。

Spring Boot 中如何配置

如果你用的是 Spring Boot + Springfox 或 Springdoc，可以通过注解把校验规则暴露到 Swagger UI 上。比如用 @NotNull、@NotBlank、@Size 这些 Bean Validation 注解，再配合 Swagger 的 @Parameter 或 @Schema，就能实现自动提示。

public ResponseEntity<User> createUser(@RequestBody @Valid CreateUserRequest request) {
    // 业务逻辑
}

其中 CreateUserRequest 类：

public class CreateUserRequest {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度应在3-20之间")
    @Schema(description = "用户名", example = "zhangsan", requiredMode = Schema.RequiredMode.REQUIRED)
    private String username;

    @Email(message = "邮箱格式不正确")
    @Schema(description = "用户邮箱", example = "zhangsan@example.com")
    private String email;

    @NotBlank
    @Size(min = 8, message = "密码至少8位")
    @Schema(description = "登录密码", requiredMode = Schema.RequiredMode.REQUIRED)
    private String password;

    // getter/setter 省略
}

效果什么样？

当你启动项目，打开 Swagger UI（通常是 /swagger-ui.html），点进这个接口，会看到每个字段都有描述、示例值，必填项会被星号标记，鼠标悬停还能看到长度、格式等限制。前端同事一看就知道该怎么填，测试也不用反复确认规则。

常见标注组合建议

• 字符串必填：@NotBlank + @Schema(requiredMode = REQUIRED)
• 数值范围：@Min(1) + @Max(100) + @Schema(description = "页码，1-100")
• 日期格式：@Pattern(regexp = "^\d{4}-\d{2}-\d{2}$") + 示例说明
• 枚举类型：在 @Schema 里加 enums 描述可选值

别忘了开启验证

有些项目默认不触发参数校验，需要确保控制器加了 @Validated，方法参数用了 @Valid，否则即使写了注解，后端不会主动校验，Swagger 显示的规则也就成了摆设。

小细节提升体验

给每个字段加上 example 值特别有用。比如手机号写个 13800138000，时间写个 2025-04-05，别人调试时可以直接复制粘贴，省得瞎猜格式。团队协作时，这种细节最能减少摩擦。