Swift OpenAPI 生成器

从OpenAPI文档生成Swift客户端和服务器代码。

概述

OpenAPI是用于记录HTTP服务的规范。OpenAPI文档以YAML或JSON格式编写，可以被工具读取以帮助自动化工作流程，例如生成发送和接收HTTP请求所需的代码。

Swift OpenAPI生成器是一个Swift包插件，可以生成进行API调用或实现API服务器所需的样板代码。

代码在构建时生成，因此它始终与OpenAPI文档保持同步，无需提交到源代码仓库。

特性

• 支持OpenAPI规范3.0和3.1版本。
• 支持流式请求和响应体，适用于JSON事件流和无需缓冲的大型负载等场景。
• 支持JSON、多部分、URL编码表单、base64、纯文本和原始字节，以具有类型安全属性的值类型表示。
• 客户端、服务器和中间件抽象，将生成的代码与HTTP客户端库和Web框架解耦。

要查看这些特性的实际应用，请查看示例项目列表。

使用方法

Swift OpenAPI生成器可用于生成API客户端和服务器存根。

下面你可以看到一些示例代码，或者你可以按照一步步教程进行操作。

使用生成的API客户端

生成的Client类型为OpenAPI文档中定义的每个HTTP操作提供一个方法¹，可与任何提供ClientTransport实现的HTTP库一起使用。

import OpenAPIURLSession
import Foundation

let client = Client(
    serverURL: URL(string: "http://localhost:8080/api")!,
    transport: URLSessionTransport()
)
let response = try await client.getGreeting()
print(try response.ok.body.json.message)

使用生成的API服务器存根

要实现服务器，定义一个符合生成的APIProtocol的类型，为OpenAPI文档中定义的每个HTTP操作提供一个方法¹。

服务器可以与任何提供ServerTransport实现的Web框架一起使用，这允许你将API处理程序注册到HTTP服务器。

import OpenAPIRuntime
import OpenAPIVapor
import Vapor

struct Handler: APIProtocol {
    func getGreeting(_ input: Operations.getGreeting.Input) async throws -> Operations.getGreeting.Output {
        let name = input.query.name ?? "陌生人"
        return .ok(.init(body: .json(.init(message: "你好，\(name)！"))))
    }
}

@main struct HelloWorldVaporServer {
    static func main() async throws {
        let app = Vapor.Application()
        let transport = VaporTransport(routesBuilder: app)
        let handler = Handler()
        try handler.registerHandlers(on: transport, serverURL: URL(string: "/api")!)
        try await app.execute()
    }
}

包生态系统

Swift OpenAPI生成器项目分布在多个仓库中，以实现可扩展性并最小化项目中的依赖。

要求和支持的功能

另请参阅支持的OpenAPI功能。

支持的平台和最低版本

生成器在开发过程中使用，支持macOS和Linux。

生成的代码、运行时库和传输层支持更多平台，如下所列。

文档和示例项目

要开始使用，请查看文档，其中包含分步教程。

你还可以尝试使用Swift OpenAPI生成器并与生态系统中的其他包集成的示例项目。

如果你更喜欢观看视频，请查看WWDC23的认识Swift OpenAPI生成器。