API Platform Core 中 HashMap 类型在 OpenAPI 文档生成的问题分析

在 API Platform Core 4.0.9 版本中，当使用 PHP 的 HashMap 类型（即键值对数组）作为 API 资源属性时，生成的 OpenAPI 文档存在格式问题，导致文档验证失败。本文将详细分析该问题的成因及解决方案。

问题现象

当开发者定义如下 API 资源类时：

#[ApiResource]
class Test {
    /** @var array<string, Foo> */
    public array $foos;
}

class Foo {
    public string $bar;
}

系统生成的 OpenAPI 文档中会出现无效的类型定义：

"foos": {
  "type": "object",
  "additionalProperties": {
    "type": "unknown_type"
  }
}

其中 unknown_type 不是 OpenAPI 规范认可的类型标识符，这会导致 OpenAPI 文档验证器拒绝该文档。

预期行为

正确的 OpenAPI 文档应该完整描述 HashMap 的结构，包括键类型和值类型的详细信息：

"foos": {
  "type": "object",
  "additionalProperties": {
    "type": "object",
    "properties": {
      "bar": {
        "type": "string"
      }
    }
  }
}

问题根源

通过分析 API Platform Core 的源代码，发现问题出在 SchemaPropertyMetadataFactory 类中。当处理 HashMap 类型时，系统没有正确传递键类型信息（$keyType）到类型解析方法中，导致无法正确识别和生成值类型的完整定义。

技术背景

在 OpenAPI 规范中，HashMap 结构应该使用 additionalProperties 来描述。additionalProperties 的值应该是一个完整的模式定义，描述 HashMap 中值的类型和结构。

PHP 中的 HashMap 通常使用 @var array<KeyType, ValueType> 或 @var array<string, ValueType> 的形式进行类型注解。API Platform 应该能够解析这些注解并生成对应的 OpenAPI 定义。

解决方案建议

1. 确保类型解析时正确处理键类型信息
2. 对于复杂类型的 HashMap 值，递归生成完整的类型定义
3. 避免使用 unknown_type 这种非标准类型标识符

影响范围

该问题主要影响以下场景：

• 使用 HashMap 结构作为 API 资源属性的情况
• 需要严格验证 OpenAPI 文档的工作流程
• 前端开发人员依赖准确 API 文档的情况

临时解决方案

在问题修复前，开发者可以通过以下方式缓解：

1. 使用 DTO 替代 HashMap 结构
2. 手动修改生成的 OpenAPI 文档
3. 关闭 OpenAPI 文档的严格验证

总结

API Platform Core 在处理 HashMap 类型时生成的 OpenAPI 文档存在格式问题，这会影响文档验证和前端开发。问题的核心在于类型解析过程中键类型信息的丢失。开发者需要注意这个问题，并期待官方在后续版本中修复。