Swift OpenAPI Generator 中枚举类型在查询参数中的类型推导问题

在 Swift OpenAPI Generator 项目中，开发者发现了一个关于枚举类型在查询参数中类型推导的有趣现象。当在 OpenAPI 规范中定义查询参数时，如果使用枚举类型但没有显式指定类型，会导致生成的 Swift 代码不够类型安全。

问题现象

在 OpenAPI 规范中定义查询参数时，如果使用数组形式的枚举值但没有指定具体类型：

- name: salutation
  required: false
  in: query
  schema:
    type: array
    items:
      enum:
        - CAPTAIN
        - DOCTOR
        - YOUR_HONOR

生成的 Swift 代码会使用 OpenAPIRuntime.OpenAPIValueContainer 这种通用容器类型，而不是预期的类型安全枚举：

internal var salutation: [OpenAPIRuntime.OpenAPIValueContainer]?

解决方案

解决这个问题的方法很简单：在枚举定义中显式指定类型为字符串：

- name: salutation
  required: false
  in: query
  schema:
    type: array
    items:
      type: string  # 关键添加
      enum:
        - CAPTAIN
        - DOCTOR
        - YOUR_HONOR

这样生成的代码就会是类型安全的枚举：

internal enum salutationPayload: String, Codable, Hashable, Sendable, CaseIterable {
    case CAPTAIN = "CAPTAIN"
    case DOCTOR = "DOCTOR"
    case YOUR_HONOR = "YOUR_HONOR"
}
internal var salutation: [Operations.getGreeting.Input.Query.salutationPayload]?

技术背景

这个问题的根源在于 OpenAPI 规范中枚举类型的灵活性。枚举可以应用于多种基础类型，包括但不限于字符串和整数。在没有显式指定类型的情况下，Swift OpenAPI Generator 无法确定应该将枚举值映射为何种 Swift 类型。

在 OpenAPI 规范中，enum 关键字可以用于任何类型的 schema，而不仅仅是字符串。例如，也可以定义数字枚举：

enum:
  - 1
  - 2
  - 3

因此，工具无法安全地从枚举值本身推断出确切的类型，特别是在 YAML 格式中，字符串和数字有时可能看起来相似（例如 "123" 和 123）。

最佳实践

基于这个发现，建议开发者在定义 OpenAPI 规范时：

1. 总是为枚举显式指定类型
2. 对于字符串枚举，明确使用 type: string
3. 对于数组中的枚举项，确保数组元素的类型也被明确指定

这种做法不仅能确保生成的 Swift 代码是类型安全的，还能使 API 规范更加明确和自文档化。

结论

Swift OpenAPI Generator 在处理查询参数中的枚举类型时，需要开发者显式指定类型信息才能生成最优的类型安全代码。这反映了 API 设计中的一个重要原则：显式优于隐式。通过明确指定类型，可以避免潜在的歧义，确保生成的客户端代码既安全又易于使用。