OpenAPI Generator字典定义异常：无法指定Map值类型问题

我使用OpenAPI Gradle Plugin 6.2.1，基于以下OpenAPI 3.1.0规范生成Java（Spring）代码：

openapi: 3.1.0
info:
  title: My-API
  version: 0.0.1
paths:
  /module:
    get:
      operationId: listModules
      summary: get modules
      tags:
        - Modules
      responses:
        "200":
          description: OK
          content:
           application/json:
            schema:
              $ref: '#/components/schemas/Module'

components:
  schemas:
    Module:
      type: object
      description: A module
      properties:
        id:
          type: string
          format: uuid
        metaData:
          type: object
          additionalProperties:
            type: string

按OpenAPI官方规范，用additionalProperties定义String到String的Map是正确写法，但代码生成时抛出异常：

java.lang.IllegalArgumentException: Cannot deserialize value of type <code>java.lang.Boolean</code> from Object value (token <code>JsonToken.START_OBJECT</code>)
at [Source: UNKNOWN; byte offset: #UNKNOWN]

若将additionalProperties改为布尔值additionalProperties: true，代码生成成功，但生成的是Map<String, Object>。我需要指定值类型，甚至尝试引用复杂类型：

additionalProperties:
  $ref: '#/components/schemas/MetaDataItem'

但仍报相同异常，请问问题出在哪里？

问题原因与解决方案 #

1. 核心原因：插件版本对OpenAPI 3.1的兼容性缺陷 #

OpenAPI Gradle Plugin 6.2.1底层依赖的OpenAPI Generator版本，对OpenAPI 3.1规范中additionalProperties的对象形式解析存在bug，无法正确识别类型定义，误将对象结构当作布尔值处理，从而抛出反序列化异常。

2. 具体解决方法 #

方法一：升级插件版本到7.x及以上

新版本的OpenAPI Gradle Plugin（7.x及更高）已完善对OpenAPI 3.1的支持，能正确解析additionalProperties的对象定义，生成指定类型的Map（如Map<String, String>）。

修改build.gradle中的插件依赖：

plugins {
    id "org.openapi.generator" version "7.6.0" // 选择最新稳定版
}

方法二：临时降级OpenAPI规范版本到3.0.x

如果暂时无法升级插件，可将OpenAPI规范的版本从3.1.0改为3.0.3，插件6.x版本对3.0系列规范的支持更成熟，能正常处理additionalProperties的类型定义。

修改规范头部：

openapi: 3.0.3

方法三：配置生成器参数强制指定类型

在Gradle的openApiGenerate任务中添加配置参数，强制指定additionalProperties的值类型，部分场景下可绕过解析bug：

openApiGenerate {
    generatorName = "spring"
    inputSpec = "$rootDir/src/main/resources/openapi.yaml"
    outputDir = "$buildDir/generated"
    apiPackage = "com.example.api"
    modelPackage = "com.example.model"
    configOptions = [
        additionalPropertyType: "java.lang.String" // 全局指定值类型，按需调整
    ]
}

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