OpenAPI から Python SDK を自動生成するツールまとめ
まちゅけんOpenAPI 仕様 (openapi.yaml) から Client SDK を自動生成するツールを検索したら割と乱立しているように見えたので、有名どころのものをまとめます。 Zenn の GitHub プレビューを活用して参考文献は積極的に公式リポジトリから引用します。
筆者はクライアント側 Python コードを生成する目線でこのスクラップをまとめています 🐍
- 紹介するコンテンツ
- Swagger Codegen
- OpenAPI Generator
- openapi-python-client
- Stainless
- etc ...
(前提) OpenAPI 仕様とは
OpenAPI とは
OpenAPI 仕様は、HTTP API を記述するための正式な標準を提供します。
これにより、APIの仕組みの理解、クライアントコードの生成、テストの作成、設計標準の適用などが可能になります。
まちゅけんSwagger Codegen
組織
Swagger (会社名: SmartBear)
Swagger は OpenAPI の前身です。 OpenAPI 3.0 より前は Swagger 仕様という名前でした。 SmartBear は 2015 年に Swagger 仕様を OpenAPI 仕様として Linux foundation に寄贈されそこから OpenAPI Initiative が設立されました。
Swagger (SmartBear) としては寄贈後は OpenAPI 仕様を利用する為のエコシステムを開発しており、Swagger Codegen がそのうちの一つのようです。
リリース
初期リリースは 2012 年になっています。
これを書いている現在も活発に開発されているようです。
ツール実装
恐らく Java で実装された Mustache というテンプレートエンジンによって生成するツールになっています。
対応言語
Python クライアントだけでなくサーバーにも対応しています。 他にも様々な言語に対応しています。
生成コード仕様
生成される Python クライアントコードとしては urllib3 に依存しているようです。
非同期の asyncio 版もあって aiohttp に依存しています。
生成方法
Docker コマンドでコードを生成できます。
生成コード利用方法
同期版
非同期版 (async / await がないので生成された README.md が間違っていそう?)
まちゅけんOpenAPI Generator
組織
コミュニティ (OpenAPITools) によって管理されているようです。
そして OpenAPI Generator は前述の Swagger Codegen の Fork のようです。
OpenAPITools/openapi-generator/docs/faq.md
Swagger Codegen と OpenAPI Generator の違いは何ですか?
Swagger Codegen は SmartBear によって駆動され、OpenAPI Generator はコミュニティによって駆動されます。Swagger Codegen の 40 人以上のトップ コントリビューターとテンプレート作成者が、創設チーム メンバーとして OpenAPI Generator に参加しています。詳細については、フォークの Q&A を参照してください。SwaggerはSmartBearが所有する商標であり、このプロジェクトでの「Swagger」という用語の使用は、デモ(参照)のみを目的としています。
OpenAPITools/openapi-generator/docs/qna.md
なぜSwagger Codegenをフォークすることにしたのですか?
それにはいくつかの理由があります。創設メンバーは、Swagger Codegen 3.0.0 が Swagger Codegen 2.x の哲学から大きく逸脱しすぎていると感じていました。
創設メンバーは、2 つの別々のブランチ (2.x、3.x) のメンテナンスオーバーヘッドが、Python コミュニティで感じられているのと同様の問題を引き起こすことを懸念していました。
創設メンバーは、ユーザーが安定したリリースを取得するために数か月待つ必要がないように、より迅速なリリースサイクル(毎週のパッチリリース、毎月のマイナーリリース)を望んでいました。
コミュニティ主導のバージョンを持つことで、イノベーション、信頼性、およびコミュニティが所有するロードマップが可能になります。
組織名 (OpenAPITools) 的に OpenAPI Initiative 公式のツールかと混乱しそうですが公式のツールという訳ではなく、かといって (以前の公式の) Swagger Codegen から Fork されその Fork 元からの開発者も参加しているというのがこのツールの姿のようです。 (このスクラップはこの事実を調べようと思ったのが動機でした)
リリース
2018 年に最初のリリースがあります。
これを書いている現在も活発に開発されています。
ツール実装
Fork なので Swagger Codegen と同じまたは同系統だと思われます。
対応言語
これも同様に Python クライアントだけでなくサーバーにも対応していて、他にも様々な言語に対応しています。 ただし勿論生成されるコードは異なるでしょう。 サーバー側は Swagger Codegen は Flask のみなのに対して、こちらの OpenAPI Generator は FastAPI の対応があります。
生成コード仕様
こちらも urllib3 に依存しており、さらに Pydantic V2 もあります。 ただし非同期版はない模様? です。
生成方法
これも同様に Docker コマンドでコードを生成できます。
生成コード利用方法
まちゅけんopenapi-python-client
組織
コミュニティ (openapi-generators) によって管理されているようです。 OpenAPI Initiative とは関係なさそうです。
ただしライセンスには Triax Technologies とあります。
そこでリポジトリを検索すると Discussion にて言及がみられました。
今後数週間のうちに、openapi-python-clientをtriaxtec orgから、純粋なオープンソースコミュニティ主導のorgに移行する予定です。このディスカッションは、この変更が起こる前に皆さんにこの変更について知ってもらい、出てきた質問、コメント、懸念に対処する機会を提供するために作成しました。
何が？
このリポジトリは新しい組織に移され、すべての将来の開発、リリース、議論、問題などはその新しい組織の下で行われます。なぜ？
このプロジェクトはこれまで以上にコミュニティ主導型になっており、それを反映させたいと考えています！Triaxの従業員は引き続きこのプロジェクトに貢献し、サポートしていきますが、Triaxの従業員以外がより大きな役割を担うことも歓迎します！もし、新しい組織で何らかの直接アクセスを持つことに興味があれば、私に知らせてください！
Triax Technologies という会社が最初に開発したものの、2021 年にコミュニティ主導に移ったようです。
リリース
2020 年に最初のリリースがあります。
これを書いている現在も活発に開発されています。
ツール実装
Python で実装されています。 Web 開発者にはなじみ深い Jinja2 テンプレートエンジンでコードを生成しています。
対応言語
ツール実装と同様に Python です。 他の言語には対応していません。 また上記 2 つとは異なりこのツールはクライアント側のコード生成のみです。
生成コード仕様
リポジトリの Discription にて Generate modern Python clients from OpenAPI と謳っており、その証に HTTP クライアントには HTTPX、データバリデーションには Pydantic V2 が利用されています。
生成方法
PyPI で配布しているので pipx などでインストール、実行ができます。 CLI は openapi-python-client というそのままの名前のコマンドになっています。
生成コード利用方法
HTTPX ベースの為か 1 つの生成コードから同期・非同期版が両方利用できます。 上記 2 つと比べてもモダンなコードベースになっています。
まちゅけんStainless
組織
Stainless という会社です。 元 Stripe 開発者の方が設立しました。
リリース
2023 年頃 ? そもそも今はアーリーアクセス ?
ツール実装
オープンソースではないので不明です。
対応言語
Python 以外にも Node / TypeScript、Go、Java、Kotlin のクライアントに対応しています。
生成コード仕様
オープンソースではないですが、SDK として生成された結果である openai-python を見てみましょう。
前述の openapi-python-client と同じで HTTP クライアントには HTTPX、データバリデーションには Pydantic V2 が利用されています。
生成方法
非公開ですが、デモ SDK や openai-python のように Stainelss と契約しているとみられる SDK リポジトリをチェックしてみると、アプリの OpenAPI 仕様が更新されたら 組織の bot から生成されたコードの Pull request が飛んできて自動でマージされる ようにみえます。 製品のコアは非公開にしつつ、契約者には全自動で更新を適用する ... なんと素晴らしいビジネスの展開方法なのでしょう ✨
生成コード利用方法
こちらも openai-python を拝借します。 同期・非同期版があり、さらにストリーミングの API もあるようで SDK の API も洗練されており使い易そうです。
まちゅけんその他
今回情報収集している際に見つけた個人の草リポジトリです。 どちらもモダンな手法を用いて SDK を生成するアプローチのように見えます。
datamodel-code-generator
SDK の生成ツールではないですが、OpenAPI 仕様から Pydantic モデルを生成してくれるツールです。
Pydantic Docs からもリンクされている程のツールみたいです。
まちゅけんまとめ
乱立している (ようにみえた) ツール群をまとめました。
まとめる前は特に以下の 3 つは名称的にも どれがファーストパーティー寄りでどれがサードパーティーのツールなのか が全く分かりませんでした。
- Swagger Codegen (
swagger-api/swagger-codegen) - OpenAPI Generator (
OpenAPITools/openapi-generator) - openapi-python-client (
openapi-generators/openapi-python-client)
(だって OpenAPI 仕様公式リポジトリは OAI/OpenAPI-Specification なんですよ ?!)
今回調べたおかげてとてもすっきりしました。
また Stainless は主観的には紹介した中で最も素晴らしい SDK 生成ツールですが、オープンソースではなくエンタープライズ向け ? なのが残念です 🥲 一応無料で試してみる、という応募フォームは存在します。 (https://www.stainlessapi.com/try)
しかしながら Stainless によって生成された SDK のコードを学んでいだけでも心が躍ります。 今後の動向に期待しましょう。
またこのスクラップでは情報収集しただけであり、手を動かして触ってみた所の情報ではありません。
情報収集は終了したということでスクラップはクローズして、出来れば今後実際にコード生成して SDK の使用感を試してみたいと思います 🫡
まちゅけんKiota
組織
Microsoft
リリース
2021 年に最初のリリースがあり、2023 年に GA しています。
これを書いている現在も活発に開発されています。
ツール実装
C#
対応言語
生成コード仕様
HTTP クライアントには HTTPX、データバリデーションには dataclass が利用されています。
生成方法
生成コード利用方法