Swift OpenAPI Generator 中的响应类型解析问题解析

背景介绍

在 Swift OpenAPI Generator 项目中，开发者遇到了一个关于 API 响应类型解析的有趣问题。当服务器返回一个包含详细信息的 JSON 响应时，客户端代码却将其解析为一个更简单的结构体。这种现象揭示了 OpenAPI 规范中 oneOf 和 anyOf 关键字在实际应用中的行为差异。

问题现象

开发者定义了两个响应结构体：

1. CreateTranscriptionResponseJson - 仅包含转录文本的简单结构
2. CreateTranscriptionResponseVerboseJson - 包含语言、时长、单词时间戳等详细信息的复杂结构

尽管服务器返回的是详细响应，但客户端总是将其解析为简单结构。这是因为简单结构是详细结构的子集，而解码器会按顺序尝试解析每个可能的类型。

技术分析

OpenAPI 的组合关键字

OpenAPI 规范提供了几种组合模式的关键字：

1. oneOf - 响应必须精确匹配其中一个模式
2. anyOf - 响应可以匹配一个或多个模式
3. allOf - 响应必须匹配所有指定的模式

在默认实现中，解码器会按顺序尝试每个可能的模式，直到找到第一个能够成功解码的类型。这就是为什么子集结构会被优先匹配的原因。

解码器的工作机制

Swift OpenAPI Generator 生成的解码代码大致如下：

public init(from decoder: any Decoder) throws {
    var errors: [any Error] = []
    do {
        value1 = try .init(from: decoder)
    } catch {
        errors.append(error)
    }
    do {
        value2 = try .init(from: decoder)
    } catch {
        errors.append(error)
    }
    // 验证至少有一个模式匹配成功
    try Swift.DecodingError.verifyAtLeastOneSchemaIsNotNil(
        [value1, value2],
        type: Self.self,
        codingPath: decoder.codingPath,
        errors: errors
    )
}

这种实现意味着解码顺序会影响结果，特别是当一种类型是另一种类型的子集时。

解决方案

开发者最终发现并解决了两个关键问题：

1. 类型定义问题：API 规范中将数值类型错误地定义为字符串类型，导致详细结构的解码失败
2. 顺序问题：在 anyOf 或 oneOf 中，将更具体的类型放在前面可以提高匹配成功率

最佳实践建议

1. 精确的类型定义：确保 API 规范中所有字段的类型定义准确无误
2. 合理的组合顺序：在 anyOf 或 oneOf 中，将更具体、更复杂的类型放在前面
3. 考虑使用 discriminator：虽然在这个案例中不适用，但在有明确类型标识的情况下，discriminator 可以提供更可靠的类型区分
4. 测试验证：编写单元测试验证各种响应情况下的解析行为

总结

这个案例展示了 API 客户端代码生成中类型解析的微妙之处。理解 OpenAPI 的组合关键字和解码器的工作机制，对于设计可靠的 API 接口和客户端代码至关重要。通过精确的类型定义和合理的结构设计，可以避免这类解析歧义问题。