认识 Swift OpenAPI Generator

一句话判断

OpenAPI 规范驱动的代码生成，让 Swift 调用 REST API 从样板代码地狱中解脱出来。

这场 Session 讲了什么

Swift OpenAPI Generator 是一个新的 Swift Package 插件，在构建时根据 OpenAPI 文档自动生成类型安全的网络请求代码。OpenAPI 是一个定义 HTTP 服务的开放标准，使用 YAML 或 JSON 格式描述 API 的路径、方法、参数和响应。

没有代码生成时，调用一个简单的 API 需要手动构建 URL、设置请求参数、发起请求、验证响应状态码和内容类型、解码 JSON——这些样板代码在大型 API 中会变得难以维护。使用 Swift OpenAPI Generator 后，你可以使用类型安全的输入，获得丰富的枚举类型输出，编译器会确保你处理了所有文档中描述的响应类型。

生成的代码不绑定特定的 HTTP 客户端库，你需要选择一个集成包。对于 iOS app，推荐使用 URLSession 集成包。整个生成过程在构建时完成，生成的代码始终与 OpenAPI 文档保持同步。

值得深挖的点

生成的 Client 类型提供了完全类型安全的 API 调用体验。输入参数有强类型，响应是枚举类型，每个 case 对应文档中描述的一种响应状态码和内容类型。这意味着如果你忘记处理某个错误响应，编译器会提醒你。

配置过程涉及添加三个包依赖：swift-openapi-generator（插件）、swift-openapi-runtime（通用类型）和选择的 HTTP 客户端集成包。你还需要将 OpenAPI 文档和插件配置文件添加到 target 的源目录中。

代码片段

// OpenAPI 文档示例 (YAML)
// openapi: '3.0.0'
// info:
//   title: Cat Faces API
// paths:
//   /emoji:
//     get:
//       operationId: getEmoji
//       responses:
//         '200':
//           content:
//             application/json:

// 使用生成的 Client
let client = Client(
    serverURL: URL(string: "http://localhost:8080")!,
    transport: URLSessionTransport()
)

let response = try await client.getEmoji()
switch response {
case .ok(let body):
    // body 是强类型
    let emoji = body.json.emoji
case .undocumented(let statusCode, _):
    // 处理未文档化的响应
    break
}

最佳实践

• 将 OpenAPI 文档纳入版本控制，作为 API 的单一事实来源
• 使用生成的 Client 类型替代手写网络请求代码
• 利用枚举响应类型确保所有场景都被处理
• 选择合适的 HTTP 客户端集成包（iOS 用 URLSession）
• 插件配置文件允许你自定义生成行为

还有什么值得关注

• Swift OpenAPI Generator 支持服务端和客户端
• 生成的代码不依赖任何特定的 HTTP 库
• OpenAPI 生态系统提供丰富的工具：交互式文档、测试生成等
• 参考 “Meet Swift package plugins” 了解插件机制