FrontEnd

Orvalを使ってFastAPIが生成したOpenAPIからAPIクライアントを生成してみる

投稿日:

はじめに

orvalはOpenAPIからTypeScript用のAPIクライアントと、APIのリクエスト/レスポンスで使うオブジェクトやEnumの型定義を生成するツールです。
今回はorvalを使って、FastAPIが生成したOpenAPIからコード生成する導入方法と、カスタマイズしておいた方が良い点について紹介したいと思います。

orvalは以下のような特徴があります。

  • axiosに対応(既存のaxiosInstanceをそのまま使うことができるので、インターセプターを使った既存の仕組みもそのまま使用可能)
  • fetchにも対応(axiosである必要がない場合、容量を削減することができる)
  • Node.jsさえあればorvalを実行可能
  • APIクライアントのカスタマイズが容易
  • Tanstack Queryのコードを生成することも可能
  • MSW用のモックを生成できる

それでは、ここからはFastAPI + orvalの構成で説明していきます。

FastAPI側の準備

今回はサンプルとしてCRUDを用意します。(APIの定義さえあれば良いので処理はダミーとなっています。)

FastAPI側のポイントは2点です。

1点目は、 BaseSchema を定義し、それを継承して Pet を定義していることです。 BaseSchema ではリクエスト・レスポンスでキャメルケースを受けるために必要な設定をしています。
Pythonではスネークケースを使い、TypeScriptではキャメルケースを使いたいということはよくあると思います。その問題を解決するため、このような設定をしています。
この設定をすることで、FastAPIが出力するOpenAPI上もキャメルケースになってくれるため、orvalでの生成結果もキャメルケースにすることができます。

2点目は、 APIRouter を生成するときにタグを指定している点です。ここでタグを指定すると、 APIRouter に紐づくAPIには同じタグが振られるようになります。
orvalは出力ファイルをタグ単位で分割することができるので、そのために指定しています。

orvalのセットアップとコード生成

まずはorvalを追加します。orvalは実行時には不要なので、devDependencies に追加するようにします。

次に orval.config.ts ファイルを作成し、設定をしていきます。

ここで特におすすめなのが modeoperationName の設定です。
まず、 mode は出力するファイルをどのように分割するかを設定します。デフォルトは single となっていて1つのファイルに全て出力されます。
今回は tags-split となっていて、以下のようにタグごとにファイルが分けられます。(これが最も細かく分割されるモードです)

次に operationName のカスタマイズです。この設定をしない状態だと、以下のようなAPIクライアントが生成されます。

関数名がとてもわかりにくいものとなってしまっています。この関数名はデフォルトでOpenAPIの operationId から生成されますが、FastAPIが生成するOpenAPI以下のようになっていて、かなり分かりにくいものとなっています。

このOpenAPIを眺めてみると、 summary はFastAPIで定義した関数名が使用されていることに気が付きます。
このテキストであれば、APIクライアントの関数名に使用できそうです。ただし、このままでは使用できないため、以下のように、空白を除去し先頭を小文字にすることで、キャメルケースに変換した上で使用しています。

最後に、コマンド pnpm orval --config ./orval.config.ts を実行すればコードが生成されます。

生成されたコードの確認

まずは petstore.schemas.ts を見ていきます。このファイルにはAPIで使用するオブジェクトの型やEnumが定義されています。

このファイルで注目したい点は interface Pet の各フィールド名がキャメルケースとなっている点です。先ほど説明した通り、PydanticモデルのConnfigの設定が、FastAPIが出力するOpenAPIに反映されているため、orvalが生成するTypeSciprtの型もキャメルケースになりました。

次に、APIクライアントである pets/pets.ts を見ていきます。

このファイルで注目したい点は、各関数名です。先ほど orval.config.tsoperationName の生成をカスタマイズし、OpenAPIの summary から生成するようにしたので、分かりやすい関数名になっています。

さいごに

FastAPI + orvalの組み合わせの場合、双方の設定をカスタムすることで実用的なAPIクライアントを生成することができました。

おすすめ書籍

Reactハンズオンラーニング 第2版 ―Webアプリケーション開発のベストプラクティス プログラミングTypeScript ―スケールするJavaScriptアプリケーション開発

blog-page_footer_336




blog-page_footer_336




-FrontEnd
-, , ,

執筆者:

免責事項

このブログは、記事上部に記載のある投稿日時点の一般的な情報を提供するものであり、投資等の勧誘・法的・税務上の助言を提供するものではありません。仮想通貨の投資・損益計算は複雑であり、個々の取引状況や法律の変更によって異なる可能性があります。ブログに記載された情報は参考程度のものであり、特定の状況に基づいた行動の決定には専門家の助言を求めることをお勧めします。当ブログの情報に基づいた行動に関連して生じた損失やリスクについて、筆者は責任を負いかねます。最新の法律や税務情報を確認し、必要に応じて専門家に相談することをお勧めします。


comment

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

CAPTCHA


関連記事

js

Reactを始める前に知っておきたいES2015/ES6の機能

1 はじめに2 ECMAScript – ES2015/ES6とは3 変数と定数とスコープ4 テンプレート文字列5 分割代入6 デフォルト引数7 残余引数(レストパラメータ)8 展開(スプ ...

React Router v7 + Cloudflare PagesでのOGPタグ設定とOGP画像生成

1 はじめに2 OGPタグの設定2.1 全体で共通の設定2.2 meta()関数による動的な設定3 OGP画像の生成3.1 @vercel/ogの導入3.2 middlwareの実装4 OGPチェッカ ...

Vue.jsでWebアプリケーションを作る〜Vue.jsの基礎〜

1 はじめに1.1 Vue.jsとは1.2 インストール1.3 Vueアプリケーションを作る2 データを表示する2.1 文字列を表示する2.2 HTMLで表示する3 属性を指定する3.1 インラインス ...

Vue CLIでPWAが簡単に実装できる 〜 Service Worker と A2HS 〜

1 はじめに2 環境構築2.1 Vue CLIをインストール2.2 プロジェクトを作成2.3 PWA選択時に追加されるファイル2.4 動作確認時の注意3 Service Worker3.1 Servi ...

AMPに対応してモバイルページを高速に表示させる

1 はじめに2 AMPとは3 なぜAMPでは高速に表示されるのか3.1 非同期スクリプトのみを許可3.2 リソース読み込みに優先度を付ける3.3 プリレンダリング4 AMPの3要素4.1 AMP HT ...

フォロー

blog-page_side_responsive

2025年6月
1234567
891011121314
15161718192021
22232425262728
2930  

アプリ情報

私たちは無料アプリもリリースしています、ぜひご覧ください。 下記のアイコンから無料でダウンロードできます。