Swift OpenAPI Generator 概览

Apple 推出了一个开源工具包——Swift OpenAPI Generator，旨在通过 OpenAPI 文档生成处理客户端/服务器通信所需的代码。该工具包为每个操作的输入和输出生成类型安全的表示，并生成处理请求和响应的网络调用代码，同时为服务器端生成存根以将请求处理委托给处理程序。

主要功能

1. 生成类型安全的代码
   Swift OpenAPI Generator 生成客户端和服务器代码，这些代码基于一个生成的 APIProtocol 类型，该类型包含每个 OpenAPI 操作的方法。例如，对于一个支持 HTTP GET 请求的 GreetingService，APIProtocol 将包含一个 getGreeting 方法。

2. 客户端和服务器代码生成

   • 客户端：生成一个实现 APIProtocol 的 Client 类型，用于客户端。
   • 服务器端：生成一个 registerHandlers 方法，用于注册协议中每个操作的处理程序。
3. 不涉及的功能
   生成的代码不涵盖认证、日志记录或重试逻辑，因为这些功能通常与业务逻辑紧密相关，难以抽象化。开发者可以通过实现符合 ClientMiddleware 或 ServerMiddleware 协议的中间件来实现这些功能。

代码生成的灵活性

• 不依赖特定 HTTP 框架
  生成的代码不绑定到特定的 HTTP 框架，而是依赖于通用的 ClientTransport 或 ServerTransport 类型。任何兼容的 HTTP 框架都可以通过实现这些类型来使用该生成器。
• 支持的框架
  目前支持多个现有的传输框架，包括 iOS 的 URLSession、AsyncHTTPClient 的 HTTPClient、Vapor 和 Hummingbird。

运行方式

1. 作为 Swift Package Manager 插件
   可以通过 YAML 配置文件 openapi-generator-config.yaml 控制生成过程，指定生成客户端代码、服务器代码或两者。

2. 通过 CLI 手动运行
   支持通过命令行选项进行配置，例如：

   swift run swift-openapi-generator \
       --mode types --mode client \
       --output-directory path/to/desired/output-dir \
       path/to/openapi.yaml

依赖项目

所有协议和类型都在其配套项目 Swift OpenAPI Runtime 中定义，生成的客户端和服务器代码依赖于此项目。

当前状态与未来计划

Swift OpenAPI Generator 目前仍处于早期阶段，虽然支持大多数 OpenAPI 常用功能，但仍缺乏一些期望的功能，这些功能正在开发中。