Swagger/OpenAPI 生成工具 for Swift (iOS/macOS)

Swagger/OpenAPI 生成工具 for Swift (iOS/macOS)：工具完整概述

iOS/macOS 移动应用开发通常需要集成 REST API。手动编写网络层既耗时又容易出错，尤其是在规范频繁变更的情况下。解决方案是从 OpenAPI（原 Swagger）规范生成 Swift 代码。本文将介绍主要工具、其功能及使用示例。

什么是 OpenAPI，为什么 Swift 开发者需要它？

OpenAPI 是一种以 YAML 或 JSON 格式描述 REST API 的标准。它包含所有端点、参数、数据模型和响应代码的信息。从这种描述生成代码可以实现：

自动创建类型化的数据模型（struct, enum）
生成具有正确 URL 和 HTTP 方法的安全 API 客户端
避免文档与代码之间的拼写错误和不一致
在 API 更新时节省数小时的重复性工作

Swift 代码生成的主要工具

目前最流行的有三种方法：

1. Apollo iOS

Apollo 是一个强大的 GraphQL 客户端，但其工具集也通过插件 apollo-ios-openapi 支持 OpenAPI。然而，该解决方案更侧重于 GraphQL，因此对于纯 REST 场景，最好考虑其他选项。

2. CreateAPI

CreateAPI 是一个用 Swift 编写的现代生成器。它支持 OpenAPI 3.0 和 3.1，生成使用 async/await、Combine 或基于闭包 API 的纯 Swift 代码。这是新项目的最佳选择。

3. Swagger Codegen / OpenAPI Generator

来自社区的经典解决方案。支持多种语言，包括 Swift 5。通过 CLI 或 Gradle/Maven 插件进行生成。结果包括数据模型、网络层（基于 URLSession 或 Alamofire）和协议。

CreateAPI 使用示例

我们来看一个为简单 REST API（例如用户列表）生成客户端的过程。

步骤 1. 安装

将 CreateAPI 添加到 Package.swift 或通过 Mint 安装：

// Package.swiftdependencies: [    .package(url: "https://github.com/CreateAPI/CreateAPI", from: "0.2.0")]

步骤 2. 准备 OpenAPI 规范

示例 api.yaml：

openapi: "3.0.0"info:  title: Users API  version: "1.0"paths:  /users:    get:      summary: Get all users      responses:        '200':          description: Success          content:            application/json:              schema:                type: array                items:                  $ref: '#/components/schemas/User'components:  schemas:    User:      type: object      properties:        id:          type: integer        name:          type: string        email:          type: string      required:        - id        - name

步骤 3. 生成 Swift 代码

创建配置文件 .createapi.yml：

spec: api.yamloutput: ./Generatedmodule: UsersAPI

运行生成器：

swift run create-api generate

步骤 4. 使用生成的代码

结果将得到文件 UsersAPI.swift 和 Models.swift。在应用中的使用示例：

import UsersAPI

let client = Client(baseURL: URL(string: "https://api.example.com")!)

Task {    do {        let users: [User] = try await client.users.get()        for user in users {            print("\\(user.name) (\\(user.email))")        }    } catch {        print("错误: \\(error.localizedDescription)")    }}