Swift OpenAPI Generator 发布 1.0 稳定版

于6个月前开源的Swift OpenAPI Generator现已到了稳定版。1.0 版本带来了新特性和简化的 API。

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

1.0 版本带来的新特性包括采用 AsyncSequence 来启用 JSON 事件流和无缓冲的大型负载；支持类型安全的常见内容类型，包括 JSON、多部分、URL 编码等；通过灵活的客户端和服务器端抽象更好地解耦生成的代码。

在客户端，Swift OpenAPI Generator 创建的类可以与支持 ClientTransport 协议的任何 HTTP 框架一起使用。在服务器端，可以兼容任何符合 ServerTransport 协议的 Web 框架。

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

一般来说，当你修改 OpenAPI 文档来添加新的响应、内容类型、删除必需的属性或重命名模式时，你的 Swift 代码也需要做出修改以适应新生成的代码。

例如，当向现有操作添加新的响应或向现有响应添加新的内容类型时，Swift OpenAPI Generator 将创建一个新的 enum case 来处理它。这意味着所有使用该 enum 的 switch 语句都需要显式处理这个新 case，这样才能通过编译器检查，除非它们实现了 default case。当然，default case 可以确保你的程序在编译时不会发生中断，但这并不一定意味着它将产生正确的结果。

向现有模式中添加新属性是另一种情况。如果你的代码没有捕获相应 struct 的 init 方法签名，这种修改就不会发生中断。作为一般规则，你不应该在公共 API 中包含生成的代码（包括模式初始化器）。

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

原文链接：

https://www.infoq.com/news/2024/02/swift-openapi-generator-1-0/