Swift OpenAPI Generator 介绍

我们很高兴地宣布推出一套开源库——Swift OpenAPI Generator，旨在帮助客户端和服务器开发人员通过行业标准的 OpenAPI 规范简化 HTTP 通信的工作流程。

什么是 OpenAPI？

OpenAPI 是一种用于描述 HTTP 服务的规范。它通过 YAML 或 JSON 格式编写文档，能够被工具解析，从而自动化生成发送和接收 HTTP 请求所需的代码。作为 API 契约的权威来源，OpenAPI 解决了服务与客户端之间的契约传递问题，避免了开发人员需要手动阅读可能不准确的文档或分析网络流量来理解服务调用方式的情况。

通过 OpenAPI，开发者可以显著减少耗时、重复且容易出错的工作，无论是在首次集成服务时，还是在服务不断演进的过程中。

示例：GreetingService 服务

为了更直观地了解 OpenAPI 的实际优势，我们以一个名为 “GreetingService” 的简单服务为例：

监听 HTTP GET 请求，端点为 /heart。
接受一个名为 name 的可选查询参数。
返回 HTTP 状态码 200 OK，以及包含 JSON 正文的响应。

这样的服务可以通过以下 OpenAPI 文档进行描述：

# 示例 OpenAPI 文档
openapi: 3.0.0
info:
  title: GreetingService
  version: 1.0.0
paths:
  /heart:
    get:
      summary: 获取问候语
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  greeting:
                    type: string

什么是 Swift OpenAPI Generator？

Swift OpenAPI Generator 是一个 SwiftPM 插件，它能够解析 OpenAPI 文档，并生成以下代码：

客户端代码：用于执行 HTTP 调用。
服务器代码：用于处理 HTTP 调用。

生成的代码通过类型安全的方式，在每个操作的输入输出与底层 HTTP 请求和响应之间进行转换。无论是开发 GreetingService 的客户端应用，还是实现 GreetingService 服务本身，Swift OpenAPI Generator 都能帮助开发者专注于核心逻辑，而无需手动编写网络通信代码。

如何使用 Swift OpenAPI Generator？

要使用 Swift OpenAPI Generator 插件，您需要完成以下步骤：

1. 添加包依赖

在项目中添加以下依赖项：

包插件：swift-openapi-generator，用于在构建时执行代码生成。
运行库：swift-openapi-runtime，包含生成代码所需的协议定义和扩展。
传输实现：允许插入您选择的 HTTP 客户端库或服务器框架。

2. 配置目标

在目标中启用包插件，并为运行时库和传输库添加目标依赖项。

3. 添加配置文件

将以下两个文件添加到目标中：

openapi.yaml：描述 API 的 OpenAPI 文档。
openapi-generator-config.yaml：插件的配置文件，用于控制生成客户端代码还是服务器代码。

客户端开发

在开发客户端（如 iOS 应用程序）时，Swift OpenAPI Generator 会生成以下类型：

APIProtocol：一个 Swift 协议，每个 OpenAPI 操作对应一个方法。例如，在 GreetingService 中，APIProtocol 包含一个名为 getGreeting 的方法。
Client：一个 Swift 结构体，实现了 APIProtocol，用于对服务器进行 API 调用。

以下是实例化客户端并从服务器获取问候语的示例代码：

let client = Client()
let response = try await client.getGreeting(name: "Swift")
print(response.greeting)

服务器开发

在开发服务器时，Swift OpenAPI Generator 会生成以下类型：

APIProtocol：与客户端开发中的协议相同，每个 OpenAPI 操作对应一个方法。
APIProtocol.registerHandlers：一个方法，用于为每个 OpenAPI 操作注册处理程序。例如，您可以实现 getGreeting 方法并将其注册为处理程序。

以下是实现一个简单处理程序并启动服务器的示例代码：

struct GreetingService: APIProtocol {
    func getGreeting(name: String?) -> Greeting {
        return Greeting(greeting: "Hello, (name ?? "World")!")
    }
}

let service = GreetingService()
try await service.registerHandlers(on: server)

传输实现

目前，您可以尝试以下现有的传输实现：

AsyncHTTPClient：适用于异步 HTTP 客户端。
Vapor：一个流行的 Swift Web 框架。

开源与社区参与

Swift OpenAPI Generator 项目在开发早期即开源，旨在通过社区反馈不断完善，最终实现稳定的 1.0 版本。我们鼓励开发者查看代码库、提交问题或拉取请求，并在 Swift 论坛上分享您的想法。

总结

Swift OpenAPI Generator 为 Swift 社区提供了一种高效的工具，显著减少了开发 HTTP 客户端或服务器所需的时间和精力。通过自动生成类型安全的代码，开发者可以专注于业务逻辑，而无需担心底层网络通信的复杂性。我们期待您的参与，共同推动这一工具的发展！

原文链接: https://swift.org/blog/introducing-swift-openapi-generator/