Swagger/OpenAPI 生成用于 Swift (iOS/macOS)

为 iOS 和 macOS 开发移动应用通常需要与 REST API 集成。手动编写网络层是一个耗时且容易出错的过程。基于 OpenAPI (Swagger) 规范的代码生成工具可以自动创建类型化的 Swift 模型、网络请求，甚至完整的 API 客户端。这可以加速开发、减少错误数量，并在 API 发生变化时简化代码维护。

在本文中，我们将介绍从 OpenAPI 规范生成 Swift 代码的主要工具，展示它们的使用示例，并给出在 iOS/macOS 项目中集成的建议。

主要生成工具

目前，有几种流行的解决方案支持 Swift 作为目标语言：

OpenAPI Generator — 最流行的开源工具。支持多种语言，包括 Swift 5 和 Combine。
Swagger Codegen — OpenAPI Generator 的前身，仍受支持，但灵活性较低。
Create API — Apple 的生成器，内置于 Xcode 15+，用于从 OpenAPI 规范创建客户端。

让我们更详细地了解每一个。

用于 Swift 的 OpenAPI Generator

OpenAPI Generator 是一个通用工具，可以用作 CLI、Docker 镜像或 Gradle/Maven 插件。对于 Swift，有多个生成器可用：

swift5 — 基于 Swift 5 生成，支持 Codable、URLSession 和 Combine。
swift5-deprecated — 用于向后兼容的旧版本。

安装与使用

最简单的方法是使用 Docker：

docker run --rm -v "${PWD}:/local" \  openapitools/openapi-generator-cli generate \  -i /local/spec.yaml \  -g swift5 \  -o /local/SwiftClient

执行后，在 SwiftClient 文件夹中将出现一个包含模型、API 请求和测试的生成 Xcode 项目。

生成代码示例

假设我们有一个包含获取用户端点的规范：

openapi: 3.0.0info:  title: User API  version: 1.0.0paths:  /users/{id}:    get:      operationId: getUserById      parameters:        - name: id          in: path          required: true          schema:            type: integer      responses:        '200':          description: OK          content:            application/json:              schema:                $ref: '#/components/schemas/User'components:  schemas:    User:      type: object      properties:        id:          type: integer        name:          type: string        email:          type: string      required:        - id        - name        - email

OpenAPI Generator 将创建以下 Swift 模型：

import Foundation

public struct User: Codable {    public let id: Int    public let name: String    public let email: String

    enum CodingKeys: String, CodingKey {        case id        case name        case email    }}

以及相应的 API 方法：

import Foundationimport Combine

public class UserAPI {    public static func getUserById(id: Int) -> AnyPublisher<User, Error> {        var request = URLRequest(url: URL(string: "https://api.example.com/users/\\(id)")!)        request.httpMethod = "GET"        return URLSession.shared.dataTaskPublisher(for: request)            .map(\\.data)            .decode(type: User.self, decoder: JSONDecoder())            .eraseToAnyPublisher()    }}