如何在Java中利用Swagger（YAML文件）验证传入的REST请求？

嘿，刚好做过类似的需求，给你梳理一套在Java环境里用Swagger YAML校验REST请求的完整方案，亲测靠谱！

一、核心依赖选择 #

我个人常用Atlassian开源的swagger-request-validator，它支持Swagger 2.0和OpenAPI 3.0，能和Spring MVC无缝集成，省心不少。

Maven依赖配置 #

<dependency>
    <groupId>com.atlassian.oai</groupId>
    <artifactId>swagger-request-validator-core</artifactId>
    <version>2.21.0</version>
</dependency>
<dependency>
    <groupId>com.atlassian.oai</groupId>
    <artifactId>swagger-request-validator-springmvc</artifactId>
    <version>2.21.0</version>
</dependency>

如果是Gradle项目，对应配置：

implementation 'com.atlassian.oai:swagger-request-validator-core:2.21.0'
implementation 'com.atlassian.oai:swagger-request-validator-springmvc:2.21.0'

二、编写Swagger YAML规范 #

先把你的API规则定义清楚，比如下面这个创建用户的示例，包含必填字段、格式、长度限制：

openapi: 3.0.1
info:
  title: 用户管理API
  version: 1.0.0
paths:
  /api/users:
    post:
      summary: 创建新用户
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  minLength: 3
                  maxLength: 20
                email:
                  type: string
                  format: email
                age:
                  type: integer
                  minimum: 18
              required:
                - username
                - email

把这个文件放在src/main/resources下，命名为swagger.yaml即可。

三、集成校验到Spring项目 #

这里分两种方式：全局Filter自动校验，或者手动在Controller里校验，按需选择。

方式1：全局Filter自动校验（推荐） #

配置一个Spring Bean，让所有请求都经过Swagger规则校验：

import com.atlassian.oai.validator.OpenApiInteractionValidator;
import com.atlassian.oai.validator.springmvc.OpenApiValidationFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerValidationConfig {

    @Bean
    public OpenApiValidationFilter openApiValidationFilter() {
        // 加载classpath下的swagger.yaml
        final OpenApiInteractionValidator validator = OpenApiInteractionValidator.createForSpecificationUrl("classpath:/swagger.yaml")
                .build();
        return new OpenApiValidationFilter(validator);
    }
}

这样所有匹配Swagger里定义的接口请求都会自动校验，不符合规则的会抛出ValidationFailedException。

方式2：手动在Controller中校验 #

如果只想给特定接口加校验，可以手动注入校验器，在接口方法里执行校验：

import com.atlassian.oai.validator.model.Request;
import com.atlassian.oai.validator.model.SimpleRequest;
import com.atlassian.oai.validator.OpenApiInteractionValidator;
import com.atlassian.oai.validator.ValidationErrors;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import javax.servlet.http.HttpServletRequest;

@RestController
public class UserController {

    private final OpenApiInteractionValidator validator;

    // 构造注入校验器（Spring会自动装配）
    public UserController(OpenApiInteractionValidator validator) {
        this.validator = validator;
    }

    @PostMapping("/api/users")
    public String createUser(@RequestBody String requestBody, HttpServletRequest httpRequest) {
        // 构建请求对象，适配校验器要求
        final Request request = SimpleRequest.Builder.post(httpRequest.getRequestURI())
                .withContentType("application/json")
                .withBody(requestBody)
                .build();

        // 执行校验
        final ValidationErrors errors = validator.validateRequest(request);

        if (!errors.isEmpty()) {
            // 这里可以抛出自定义异常，或者直接返回错误信息
            throw new IllegalArgumentException("请求参数不符合规范: " + errors.getSummary());
        }

        // 执行业务逻辑
        return "用户创建成功";
    }
}

四、自定义错误处理 #

为了让错误返回更友好，用@ControllerAdvice统一处理校验异常：

import com.atlassian.oai.validator.springmvc.ValidationFailedException;
import com.atlassian.oai.validator.ValidationErrors;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class ValidationExceptionHandler {

    @ExceptionHandler(ValidationFailedException.class)
    public ResponseEntity<String> handleValidationError(ValidationFailedException ex) {
        final ValidationErrors errors = ex.getValidationErrors();
        // 可以把所有错误信息拼接返回，或者封装成JSON格式
        return new ResponseEntity<>("请求校验失败：" + String.join("; ", errors.getAllMessages()), HttpStatus.BAD_REQUEST);
    }
}

一些注意事项 #

• 确保Swagger YAML语法正确，可以用本地的Swagger Editor验证，避免语法错误导致校验器加载失败
• 如果是Spring Boot 3.x，注意选择适配Jakarta EE的依赖版本（目前2.21.0已经支持）
• 可以扩展校验规则，比如自定义格式校验，只需要实现CustomValidator接口并注册到校验器即可
• 如果你的API用的是Swagger 2.0（不是OpenAPI 3.0），只需要把YAML里的openapi字段改成swagger: 2.0就行，校验器会自动识别

内容的提问来源于stack exchange，提问作者Kusum Sharma