Swift OpenAPI Generator 1.0 正式发布

Swift OpenAPI Generator 在开源六个月后，现发布稳定版 1.0。此次更新带来了新功能并简化了 API。

主要功能

Swift OpenAPI Generator 是一个开源的 Swift 包插件，用于自动生成访问或实现基于 OpenAPI 描述的 HTTP 端点所需的代码。该插件在构建时运行，确保生成的代码始终与最新的 OpenAPI 描述保持一致。它能够生成用于调用 API 的代码，以及与相应服务器端服务集成的存根代码。

新特性

1. 采用 AsyncSequence：支持 JSON 事件流和大型负载的无缓冲处理。
2. 类型安全的常见内容类型：包括 JSON、multipart、URL 编码等。
3. 更好的代码解耦：通过客户端和服务器端的灵活抽象实现。

客户端与服务器端支持

• 客户端：生成的类可以与任何支持 ClientTransport 协议的 HTTP 框架一起工作。
• 服务器端：任何符合 ServerTransport 协议的 Web 框架都与之兼容。

API 稳定性与代码变更

尽管努力确保生成的代码的 API 稳定性，但修改 OpenAPI 规范后，生成的代码可能会破坏现有程序，需要修复其使用方式。这种情况可能影响客户端和服务器端代码。

常见变更场景

1. 添加新响应或内容类型：生成新的 enum 用例，所有使用该 enum 的 switch 语句需要显式处理新用例，除非使用 default 用例。
2. 添加新属性到现有模式：如果代码不捕获对应 struct 的 init 方法签名，这种变更不会破坏代码。建议不要在公共 API 中包含生成的代码（包括模式初始化器）。

兼容性

Swift OpenAPI Generator 1.0 兼容 OpenAPI 3.0 和 3.1 规范，可在 Swift Package Index 上获取。

总结

Swift OpenAPI Generator 1.0 的发布标志着其进入稳定阶段，提供了更强大的功能和更好的开发体验。开发者在使用时应注意 API 的变更可能带来的影响，并遵循最佳实践以避免潜在问题。