Swift OpenAPI Generator 1.0が正式リリースー OpenAPI 3に準拠、コードスタブを自動生成

2024年2月1日、Swift OpenAPI Generatorが、バージョン1.0を正式リリースした。このプロジェクトは、RESTfulなAPI開発におけるオープンスタンダードであるOpenAPIを活用し、エンジニアたちにAPIファーストなアプローチを提供している。

新機能のハイライト

Swift OpenAPI Generator 1.0では、OpenAPI Specificationバージョン3.0および3.1との高い互換性を誇っている。これにより、より柔軟で高度なAPIの記述が可能になり、エンジニアたちはAPI開発において新たな可能性を追求できる。

また、ストリーミングリクエストおよびレスポンスボディ、AsyncSequenceのサポートなど、よりパワフルで効率的なプログラミングが可能となっている。これにより、JSONイベントストリームや大容量のペイロードをバッファリングなしで扱うことができる。

クライアントとサーバーのコードを自動生成

Swift OpenAPI Generatorは、API呼び出しとAPIサーバーの実装に必要なコードを自動生成するSwiftパッケージプラグインだ。ビルド時に自動的に生成されるコードは、OpenAPIドキュメントと常に同期しており、手動でソースリポジトリにコミットする必要がない。これにより、エンジニアたちはよりスムーズかつ信頼性の高い開発体験を享受できる。

サンプルで見るSwift OpenAPI Generator

記事内で挙げられた「Greeting Service」の例では、OpenAPIドキュメントを元にSwift OpenAPI Generatorが生成したコードが紹介されている。エンジニアたちは、これを活用して型安全なリクエストやビジネスロジックをサポートするHTTPサーバーを効率的に構築できる。

クライアントAPI

生成されたコードは、クライアント用の型「Client」を提供している。このコードでは、URLSessionを使用してGreeting Serviceに対する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スタブ

生成されたコードは、サーバー用のSwiftプロトコル「APIProtocol」を提供し、任意のWebフレームワークと組み合わせてAPIサーバーを構築できる。記事内では、Vapor Webサーバーを使用してGreeting Serviceの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 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 1.0 Releasedを日本語で紹介したものである。詳細は元記事を参照していただきたい。