型でつなぐFastAPI × フロントエンド活用術

型でつなぐFastAPI × フロントエンド 活用術 Koki Miura(@k_miura_io)

お前誰よ • 三浦 耕生(こうき) • オフィスDXSaaSのバックエンドエンジニア • Python暦：9年(2.7がギリ現役) • 鯱.py 運営 • JAWS UG名古屋＆神戸 運営 • 俺の勉強会 運営 @k_miura_io koki.miura05

前提条件 • PythonのWebアプリケーションのフロントエンドには主に以下の2パター ンが考えられる • Jinjaを始めとしたテンプレートエンジン • VueやReactなどのフロントエンドフレームワークを使用したSPA(Single Page Application) • 本セッションでは後者のSPAとAPIの連携について取り上げる

話すこと・話さないこと • 話すこと • PythonのWebフレームワークの比較 • FastAPIによるOpenAPIの連携 • OpenAPIからTypeScriptクライアントを自動生成する方法 • 話さないこと • フロントエンドの個別フレームワーク（React, Vueなど）の詳細(スライド内 ではReactをサンプルとしてAPI接続実装を解説してます) • TypeScriptの文法や基礎的な記法

アジェンダ • FastAPIをフロントエンドのバックエンドで採用するメリット • FastAPIでの型定義とOpenAPI自動生成の基本 • OpenAPIからTypeScriptクライアントを自動生成する • 開発効率を上げるTips

アジェンダ • FastAPIをフロントエンドのバックエンドで採用するメリット • FastAPIでの型定義とOpenAPI自動生成の基本 • OpenAPIからTypeScriptクライアントを自動生成する • 開発効率を上げるTips

Webフレームワーク比較 FastAPI Django REST Framework ファイル構成 開発者が定義 ORM、ルーティングなどのファ 開発者が定義 イル構成はある程度決まって いる ORM SQL Alchemy SQL Model 専用のORM SQL Alchemy 認証 OAuth2 (以下、外部ライブラリを使用) JWT Open ID Connect 標準のセッション認証 (以下、外部ライブラリを使用) OAuth2 JWT Open ID Connect (いずれも外部ライブラリを 使用) JWT セッション認証 Open ID Connect drf-spectacularまたはdrfyasgを使用 flask-rest-apiを使用 OpenAPI対応 標準対応 Flask

なぜFastAPIを選ぶのか フロントエンドと分業するときにFastAPIは相性良い

アジェンダ • FastAPIをフロントエンドのバックエンドで採用するメリット • FastAPIでの型定義とOpenAPI自動生成の基本 • OpenAPIからTypeScriptクライアントを自動生成する • 開発効率を上げるTips

リクエスト・レスポンスの型定義 • Pydanticを使用して、リクエスト・レスポン スの型定義をClass文で定義 • デフォルトを入れておくとOpenAPIのサン プルの値として反映される • ルーティング定義でリクエスト・レスポンス の定義を呼び出す

APIのリクエスト・ レスポンスに実装 • 定義した型ヒントをAPIの実 装の中に入れることでリクエ スト、レスポンス定義をそれ ぞれ挿入することで反映する • リクエストは関数の引数にリ クエストの型ヒントを入れる • レスポンスはリクエスト定義 のデコレータ引数 response_modelか関数の戻 り値の型ヒントとしてで定義

OpenAPIの自動生成 • リクエストの定義で実装された型ヒント をもとにOpenAPIのドキュメントが動的 に生成される • デフォルトは【APIのエンドポイント】 /docs でアクセスするだけで開く • パスパラメータの型ヒントも解析して入 力項目として表示される

リッチなAPIドキュメント • OpenAPIに準拠したスキー マが動的に生成されるため、 互換したツールにも対応し ている • 標準で提供している機能と してredocが標準で提供され ている • デフォルトでは【APIのエンド ポイント】/redoc

アジェンダ • FastAPIをフロントエンドのバックエンドで採用するメリット • FastAPIでの型定義とOpenAPI自動生成の基本 • OpenAPIからTypeScriptクライアントを自動生成する • 開発効率を上げるTips

OpenAPIからAPIクライアントを自動生成 • OpenAPIは標準化されたAPI定義のフォーマッ トとなっているため様々な互換ツールが存在 する • SPAのアプリケーションでAPI通信をするため のクライアントを毎回手で実装するのは手間な ので自動化できるのが理想 • APIの定義から型が充実したTypeScriptのAPI クライアントを生成していく方法がある

Hey API • 生成されたOpenAPIのスキーマから TypeScriptに対応したAPIクライアントを作成 する方法としてHey APIがある • FastAPIのドキュメントで紹介されているのが この方法だがOpenAPI 3.1のフォーマットに対 応していれば他の変換ツールも使える • 他の対応状況は https://openapi.tools/#sdk

• https://openapi.tools/#sdk

Hey API、APIのクライアント作って

必要なインポート • 基本的に生成されたコードの中にある「.gen」 が着いたTypeScriptファイルを読み込む • 「client.gen」APIの接続情報を定義するとき に使用 • 「sdk.gen」OpenAPIで定義した各APIをコール するときに使用 • 「types.gen」APIのリクエスト・レスポンスの型 定義を参照したいときに使用(FastAPIで定義 した型のクラス名と一致している)

APIの接続情報を設定 • APIのエンドポイントや必要なヘッダーを定義 する • リクエスト時に前処理、後処理をしたいときは interceptorsを呼び出して該当の処理を追加 することができる

APIを呼び出す • sdk.genで定義されている関数を使用してAPIを呼び出す • 引数にそれぞれパスパラメータやリクエストボディを入れる

アジェンダ • FastAPIをフロントエンドのバックエンドで採用するメリット • FastAPIでの型定義とOpenAPI自動生成の基本 • OpenAPIからTypeScriptクライアントを自動生成する • 開発効率を上げるTips

Descriptionを入れる • デコレータ引数「description」にそのAPIの説明を入れると、Hey APIで変換すると きに各リクエストを行う関数のDocstringに説明を追加することができる • IDEのコード補完でも表示されるので入れとくと◎

Operation IDを活用する • FastAPIには各リクエストに対して一意のIDが振られており、これをOperation IDとい う • Open API上ではリクエストのリンクとして使われる(例：/docs#/Entries/get_entries) • 各Operation IDをもとにHey APIは各リクエストの関数名が設定される • Operation IDは任意の値を設定することができるため、APIクライアントで呼び出すと きの関数名を自由にカスタムできる

Operation IDの命名規則を設定する • 毎回OperationIDを手動でしていると重複して命名エラーを起こすことがあるので、 全体的にOperationIDの命名規則カスタムする方法がある • 関数の返り値でユニークになるようにリクエスト定義を組み合わせてデフォルトより シンプルな関数でメンテナンス性も向上する

まとめ • FastAPIの強み • 軽量で高速な動作、柔軟なファイル構成 • 型ヒントによる堅牢なAPI設計とOpenAPI自動生成 • フロントエンド連携の効率化 • OpenAPIスキーマからTypeScriptクライアントを自動生成 • Hey APIなどのツールでAPI通信の実装コストを大幅削減 • 型安全な開発でバグの早期発見・修正が可能 • 開発効率アップのTips • APIのdescriptionやOperation IDを活用し、ドキュメントや関数名を最適化 • 命名規則の統一でメンテナンス性向上

レポジトリ ←フロントエンド バックエンド→ https://github.com/Miura55/pycon-mini-channel https://github.com/Miura55/fastapi_tutorial

• https://github.com/Miura55/pycon-mini-channel
• https://github.com/Miura55/fastapi_tutorial

END