Swift OpenAPI 生成器

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

概述

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

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

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

特性

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

用法

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

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

使用生成的 API 客户端

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

import OpenAPIURLSession
import Foundation

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

使用生成的 API 服务器存根

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

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

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 ?? "Stranger"
        return .ok(.init(body: .json(.init(message: "Hello, \(name)!"))))
    }
}

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

包生态系统

Swift OpenAPI 生成器项目分布在多个存储库中，以实现可扩展性并最大限度地减少项目中的依赖项。

存储库 描述
apple/swift-openapi-generator Swift 包插件和 CLI
apple/swift-openapi-runtime 生成的代码使用的运行时库
apple/swift-openapi-urlsession 使用 URLSession 的 ClientTransport
swift-server/swift-openapi-async-http-client 使用 AsyncHTTPClient 的 ClientTransport
swift-server/swift-openapi-vapor 使用 Vapor 的 ServerTransport
swift-server/swift-openapi-hummingbird 使用 Hummingbird 的 ServerTransport
swift-server/swift-openapi-lambda 使用 AWS Lambda 的 ServerTransport

要求和支持的特性

生成器版本 支持的 OpenAPI 版本 最低 Swift 版本
1.0.0 ... main 3.0, 3.1 5.9

另请参阅支持的 OpenAPI 特性。

支持的平台和最低版本

生成器在开发期间使用，并支持 macOS 和 Linux。

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

组件 macOS Linux iOS tvOS watchOS visionOS
生成器插件和 CLI ✅ 10.15+ ✅ ✖️ ✖️ ✖️ ✖️
生成的代码和运行时库 ✅ 10.15+ ✅ ✅ 13+ ✅ 13+ ✅ 6+ ✅ 1+

注意

当使用 Visual Studio Code 或其他依赖 SourceKit-LSP 的编辑器时，编辑器可能无法正确识别同一模块中生成的代码。 作为一种解决方法，请考虑为代码生成创建一个单独的目标，然后将其导入到您的主模块中。 有关更多详细信息，请参阅 swiftlang/sourcekit-lsp#665 中的讨论。

文档和示例项目

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

您还可以尝试使用示例项目，这些项目使用 Swift OpenAPI 生成器并与其他包集成到生态系统中。

或者，如果您喜欢观看视频，请查看 WWDC23 的Meet Swift OpenAPI Generator。

脚注

  1. OpenAPI 文档示例（点击展开） 
    openapi: '3.1.0'
info:
  title: GreetingService
  version: 1.0.0
servers:
  - url: https://example.com/api
    description: Example service deployment.
paths:
  /greet:
    get:
      operationId: getGreeting
      parameters:
        - name: name
          required: false
          in: query
          description: The name used in the returned greeting.
          schema:
            type: string
      responses:
        '200':
          description: A success response with a greeting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Greeting'
components:
  schemas:
    Greeting:
      type: object
      description: A value with the greeting contents.
      properties:
        message:
          type: string
          description: The string representation of the greeting.
      required:
        - message
    ↩ ↩2