半年前にオープンソース化されたSwift OpenAPI Generatorが安定した。バージョン1.0により、新機能と簡素化されたAPIが提供される。
Swift OpenAPI GeneratorはオープンソースのSwiftパッケージプラグインで、OpenAPIを使って記述されたHTTPエンドポイントにアクセスしたり実装したりするために必要なコードを自動的に生成するために使うことができる。プラグインはビルド時に実行することができるため、生成されたコードはAPIの最新のOpenAPI記述で常に最新であることを保証し、対応するサーバー側サービスと統合するためのスタブと同様にAPIコールを行うコードを生成できる。
リリース1.0によってもたらされた新機能の中には、バッファリングなしでJSONイベントストリームと大きなペイロードを可能にするAsyncSequence
の採用、JSON、マルチパート、URLエンコードなどを含むタイプセーフの一般的なコンテンツタイプのサポート、クライアント側とサーバー側の柔軟な抽象化により生成されたコードの、より良いデカップリングが挙げられる。
クライアント側では、Swift OpenAPI Generator は、ClientTransportプロトコルをサポートする任意の HTTP フレームワークで動作するクラスを作成する。サーバー側では、ServerTransportプロトコルに準拠する任意のWebフレームワークと互換性がある。
APIの安定性を確保するために努力しているが、OpenAPI仕様を改訂した後に、生成されたコードがあなたのプログラムを壊してしまい、その使い方を修正する必要が出てくる可能性がある。これはクライアント側とサーバー側の両方のコードに影響する可能性がある。
一般的に言えば、新しいレスポンスを追加したり、新しいコンテントタイプを追加したり、必須プロパティを削除したり、スキーマの名前を変更したりするために OpenAPI ドキュメントを修正するとき、Swift のコードは新しく生成されたコードで動作するように変更が必要になる。
例えば既存の操作に新しいレスポンスを追加するとき、または既存のレスポンスに新しいコンテントタイプを追加するとき、Swift OpenAPIジェネレータはそれを処理するために新しい列挙型
を作成する。これは、その列挙型
を使用するすべてのswitch
文が、デフォルト
のケースを実装しない限り、コンパイラのチェックを通過するために、明示的にその新しいケースに対処する必要があることを意味する。もちろん、デフォルト
のケースはコンパイル時にプログラムが壊れないことを確認しますが、必ずしも正しい結果を生成することを意味しない。
やや異なるケースは、既存のスキーマに新しいプロパティを追加する場合である。この種の変更は、対応する構造体
のinit
メソッド・シグネチャをコードに取り込まなければ壊れない。一般的なルールとして、スキーマのイニシャライザを含む生成されたコードを、パブリック API に含めるべきでは決してない。
Swift OpenAPI Generator 1.0 は OpenAPI 3.0 と 3.1 の仕様と互換性があり、Swift Package Index で入手できる。