Swift OpenAPI Generator 1.0 发布

Si Beaumont Si Beaumont
Honza Dvorsky Honza Dvorsky

我们很高兴地宣布 Swift OpenAPI Generator 稳定 1.0 版本发布！

OpenAPI 是一个开放标准，用于描述 HTTP 服务的行为，并拥有丰富的工具生态系统。OpenAPI 特别出名的一个方面是生成交互式文档的工具。但是 OpenAPI 的核心动机是代码生成，这使得采用者可以使用 API 优先的方法进行服务器开发，并且由于许多现有服务以这种格式记录其 API，因此允许客户端开发人员生成类型安全、符合语言习惯的代码来调用这些 API。

许多真实世界的 API 都有数百个操作，每个操作都有丰富的请求和响应类型、标头字段、参数等等。为每个操作编写和维护此代码可能是重复的、冗长的且容易出错的。

Swift OpenAPI Generator 是一个 Swift 包插件，它生成进行 API 调用和实现 API 服务器所需的代码。代码在构建时自动生成，因此它始终与 OpenAPI 文档同步，并且不需要提交到您的源代码仓库。

自六个月前的首次发布以来，该项目收到了超过 250 个 pull request，来自 20 多位贡献者，并获得了几个新功能和一个更简单的 API。

功能亮点

快速一览

考虑一个虚构的 HTTP 服务器，它提供一个 API 端点来返回个性化问候语

% curl 'https://example.com/api/greet?name=Jane'
{
    "message": "Hello, Jane"
}

可以使用以下 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

Swift OpenAPI Generator 可以配置为生成

生成的客户端 API

生成的代码提供了一个名为 Client 的类型，该类型为 OpenAPI 文档中定义的每个操作提供了一个方法，并且可以与为 Swift OpenAPI Generator 提供集成包的任何 HTTP 库一起使用。

插件在构建时在构建系统确定的位置生成代码。要在您的项目中使用生成的代码，只需通过提供服务器 URL 和您想要使用的 HTTP 传输来创建 Client。

以下示例创建了一个 Greeting Service 客户端，该客户端使用 URLSession 发出底层 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 的 Swift 协议，该协议为 OpenAPI 文档中定义的每个操作定义了一个方法要求，并且旨在与为 Swift OpenAPI Generator 提供集成包的任何 Web 框架一起使用。

要实现 API 服务器，请定义一个符合 APIProtocol 的类型，仅为每个操作提供业务逻辑。

要启动 API 服务器，请使用生成的 registerHandlers 函数来配置 HTTP 服务器以将 HTTP 请求路由到您的处理程序。

以下示例在名为 Handler 的类型中实现了 Greeting Service API，并配置了 Vapor Web 服务器来服务 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 ?? "Stranger"
        return .ok(.init(body: .json(.init(message: "Hello, \(name)!"))))
    }
}

@main struct Server {
    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 Generator 项目被拆分到多个仓库中，以实现可扩展性并最大限度地减少项目中的依赖关系。

下一步

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

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

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

要提出问题、请求功能或报告错误，请在 Github 上联系我们 👋。