使用openapi-generator生成代码时枚举查询参数失效问题

我使用版本为7.0.0的openapi-generator-maven-plugin基于OpenAPI Swagger规范生成Java代码，插件配置如下：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi.generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

在规范中定义了枚举类型的查询参数status：

parameters:
  - in: query
    name: status
    required: false
    example: scheduled, active
    schema:
      type: string
      enum: [scheduled, active]

但插件生成的代码里该参数被定义为String类型，而非枚举：

@Parameter(name = "status", in = ParameterIn.QUERY) @Valid @RequestParam(value = "status", required = false) String status

这导致无法限制参数输入值，请问如何配置才能让查询参数生成枚举类型并仅接受预定义值？

要让openapi-generator将查询参数生成为枚举类型，需要从插件配置和OpenAPI规范两方面调整：

1. 补充插件配置参数 #

在openapi-generator-maven-plugin的执行配置中添加configOptions，强制生成枚举类并开启校验支持：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi.generator.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <configOptions>
                    <!-- 强制将枚举生成为独立的可复用类 -->
                    <generateEnumModel>true</generateEnumModel>
                    <!-- 开启Bean Validation，自动生成枚举值校验逻辑 -->
                    <useBeanValidation>true</useBeanValidation>
                    <!-- 保持枚举值与规范定义一致，避免自动转大写 -->
                    <enumPropertyNaming>original</enumPropertyNaming>
                    <!-- 可选：允许大小写不敏感的枚举值匹配 -->
                    <useEnumCaseInsensitive>true</useEnumCaseInsensitive>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 优化OpenAPI规范的枚举定义 #

将枚举定义为可复用的组件，再在参数中引用，让插件更明确地识别枚举类型：

components:
  schemas:
    StatusEnum:
      type: string
      enum: [scheduled, active]
      description: 状态枚举，仅接受scheduled或active值

parameters:
  - in: query
    name: status
    required: false
    example: scheduled
    schema:
      $ref: '#/components/schemas/StatusEnum'

3. 验证生成结果 #

调整后，插件会自动生成StatusEnum枚举类，接口参数会变为：

@Parameter(name = "status", in = ParameterIn.QUERY) @Valid @RequestParam(value = "status", required = false) StatusEnum status

同时配合useBeanValidation配置，生成的代码会自动添加校验注解，确保输入值只能是预定义的枚举选项。

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