Spring Boot项目中OpenAPI生成的枚举未实现参数校验问题

问题分析 #

你遇到的核心问题是：OpenAPI Generator生成的枚举参数未触发Spring Boot的参数校验，导致非法枚举值可以通过接口请求。这是因为默认配置下，生成器不会自动为枚举参数添加校验触发逻辑，且Spring MVC需要显式启用方法参数校验。

解决方案 #

1. 调整OpenAPI Generator Maven插件配置

在openapi-generator-maven-plugin的配置中添加参数，启用校验注解生成和枚举校验：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <!-- 使用最新稳定版本，如6.6.0 -->
    <version>6.6.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>com.your.project.api</apiPackage>
                <modelPackage>com.your.project.model</modelPackage>
                <configOptions>
                    <!-- 启用JSR-380校验注解生成 -->
                    <generateValidationAnnotation>true</generateValidationAnnotation>
                    <!-- 针对非空枚举参数启用校验 -->
                    <validateEnumIfNotNull>true</validateEnumIfNotNull>
                    <!-- 若使用Spring Boot 3，添加此配置 -->
                    <useSpringBoot3>true</useSpringBoot3>
                    <!-- 仅生成接口（根据你的需求调整） -->
                    <interfaceOnly>true</interfaceOnly>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 启用Spring MVC方法参数校验

在生成的API接口或其实现类上添加@Validated注解（来自org.springframework.validation.annotation.Validated），触发Spring对方法参数的校验：

import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.RestController;

@Validated
@RestController
public class UserApiImpl implements UserApi {
    // 实现接口方法
    @Override
    public ResponseEntity<UsersResponsePageableModel> searchUsers(...) {
        // 业务逻辑
    }
}

3. 验证枚举校验效果

当请求传入不在UserSearchSortBy枚举范围内的值时，Spring会抛出ConstraintViolationException。你可以通过全局异常处理器捕获该异常，返回标准化的错误响应：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import javax.validation.ConstraintViolationException;
import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<Map<String, String>> handleConstraintViolation(ConstraintViolationException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getConstraintViolations().forEach(violation -> {
            String paramName = violation.getPropertyPath().toString();
            String message = violation.getMessage();
            errors.put(paramName, message);
        });
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

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