🐶

【FastAPI✖️React】OpenAPIでエンドポイントを自動生成する方法

mizukich

2024/08/08に公開

はじめに

バックエンドでFastAPIを使用し、フロントエンドでReactを使ってWebアプリケーションを開発する際、OpenAPIを利用してエンドポイントを自動生成することができます。これにより、手動でAPIクライアントを作成する手間を省き、効率的に開発を進めることができます。本記事では、npmパッケージ@hey-api/openapi-tsを使用して、FastAPIのエンドポイントを自動生成し、Reactアプリケーションで利用する方法について解説します。

OpenAPIとは

OpenAPIは、RESTful APIを記述するための標準仕様で、APIのエンドポイント、リクエスト、レスポンス、認証方法などを一元的に定義します。これにより、APIの設計、ドキュメント作成、クライアントコード生成が自動化され、開発プロセスが大幅に効率化されます。

FastAPIとOpenAPIの相性

FastAPIは、OpenAPIをネイティブにサポートするモダンなPythonウェブフレームワークです。以下の特徴により、FastAPIとOpenAPIは非常に相性が良いです。

自動生成されたOpenAPIスキーマ: FastAPIは、定義されたエンドポイントに基づいて、自動的にOpenAPIスキーマを生成します。これにより、開発者は手動でスキーマを記述する必要がなくなります。
最新のOpenAPIバージョン対応: FastAPIは、OpenAPI 3.0.2をサポートしており、最新のAPI仕様に基づいて開発できます。
ドキュメント生成: FastAPIは、Swagger UIやReDocなどのドキュメントツールと統合されており、APIのインタラクティブなドキュメントを簡単に提供できます

前提条件

FastAPIのプロジェクトがすでに存在し、http://127.0.0.1:8000からアクセスできること
Reactのプロジェクトがすでに存在すること
Node.jsとnpmがインストールされていること

手順

Reactプロジェクトにopenapiをインストール

必要なnpmパッケージをインストール

npm install @hey-api/openapi-ts --save-dev

OpenAPIスキーマの取得

FastAPIのドキュメントエンドポイントからOpenAPIスキーマを取得します。

ブラウザで http://127.0.0.1:8000/openapi.json にアクセスします。

スキーマファイルをプロジェクト配下に保存します。ファイル名は openapi.json とします。

APIクライアントの自動生成

package.jsonのscriptsにgenerate-clientを追加

package.json

{
  "name": "frontend-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "generate-client": "openapi-ts --input openapi.json  --output ./src/client --client axios"
  },

npmで実行

npm run generate-client

生成された際のConfigに必要な情報を加えましょう

client/core/OpenAPI.ts

OpenAPI.ts

export const OpenAPI: OpenAPIConfig = {
	BASE: import.meta.env.VITE_BASE_URL || 'http://localhost:8000', //← ここにバックエンド側のURIを記載
	CREDENTIALS: 'include',
	ENCODE_PATH: undefined,
	HEADERS: undefined,
	PASSWORD: undefined,
	TOKEN: async () => access_token || '',//← ここで認証トークンを渡す
	USERNAME: undefined,
	VERSION: '0.1.0',
	WITH_CREDENTIALS: false,
	interceptors: {
		request: new Interceptors(),
		response: new Interceptors(),
	},
};

BASE:
- 意味: APIエンドポイントのベースURLを指定します。
- import.meta.env.VITE_BASE_URL || 'http://localhost:8000' は、環境変数 VITE_BASE_URL が設定されていればそれを使用し、設定されていなければ http://localhost:8081 を使用します。
CREDENTIALS:
- 意味: クロスオリジンリクエストに資格情報（クッキー、認証ヘッダー、TLSクライアント証明書）を含めるかどうかを指定します。
- 'include' は、クッキーを含む資格情報を常に送信することを示します。
ENCODE_PATH:
- 意味: パスをエンコードするためのカスタム関数を指定します。
- undefined はデフォルトのエンコード方法を使用することを示します。
HEADERS:
- 意味: リクエストに追加するカスタムヘッダーを指定します。また、動的にヘッダーを生成するための関数を指定することもできます。
- undefined はデフォルトのヘッダーを使用することを示します。
PASSWORD:
- 意味: 認証に使用するパスワードを指定します。また、動的にパスワードを生成するための関数を指定することもできます。
- undefined はパスワードを使用しないことを示します。
TOKEN:
- 意味: 認証に使用するトークンを指定します。また、動的にトークンを生成するための関数を指定することもできます。
- async () => access_token || '' は、getLoginResponse 関数から取得したアクセストークンを使用し、トークンが存在しない場合は空文字列を使用します。
USERNAME:
- 意味: 認証に使用するユーザー名を指定します。また、動的にユーザー名を生成するための関数を指定することもできます。
- undefined はユーザー名を使用しないことを示します。
VERSION:
- 意味: APIのバージョンを指定します。
- '0.1.0' はAPIのバージョンが 0.1.0 であることを示します。
WITH_CREDENTIALS:
- 意味: クロスオリジンリクエストに資格情報（クッキー、認証ヘッダー、TLSクライアント証明書）を含めるかどうかを指定します。
- false は、資格情報を含めないことを示します。
interceptors:
- 意味: リクエストやレスポンスをインターセプトするためのカスタム関数を指定します。
- request: new Interceptors() は、リクエストをインターセプトするためのインターセプターの設定です。
- response: new Interceptors() は、レスポンスをインターセプトするためのインターセプターの設定です。

APIを更新するたびにConfigがリセットされない様にしたい

せっかくConfigを設定したのにgenerate-openapiするたびにリセットされてしまうのは嫌ですね
そこでopenapi-generateを実行する際、

configファイルを保存
generate-openapiで更新
保存したconfigファイルを元にconfigだけ元に戻す

となる様にしました。

`update_openapi.sh` を作成

スクリプトをプロジェクトのルートディレクトリに保存

update_openapi.sh

#!/bin/bash

# ディレクトリの設定
CONFIG_DIR="src/client/core"
BACKUP_DIR="backup"
CONFIG_FILE="OpenAPI.ts"

# バックアップディレクトリが存在しない場合は作成
if [ ! -d "$BACKUP_DIR" ]; then
  mkdir -p "$BACKUP_DIR"
fi

# Configファイルをバックアップディレクトリにコピー
cp "$CONFIG_DIR/$CONFIG_FILE" "$BACKUP_DIR/$CONFIG_FILE"

echo "Configファイルをバックアップしました。"

# OpenAPIエンドポイントの自動生成を実行
openapi-ts --input openapi.json --output ./src/client --client axios

echo "OpenAPIエンドポイントの自動生成が完了しました。"

# バックアップしたConfigファイルを元の場所にコピーして復元
cp "$BACKUP_DIR/$CONFIG_FILE" "$CONFIG_DIR/$CONFIG_FILE"

echo "Configファイルを復元しました。"

# バックアップファイルを削除
rm -r "$BACKUP_DIR"
echo "バックアップファイルを削除しました。"

echo "更新プロセスが完了しました。"

package.jsonの変更

package.json

"scripts": {
    "start": "webpack serve --mode development --open",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src",
    "format": "prettier --write ./src/**/*.{ts,tsx}",
    "generate-client": "./update_openapi.sh" #ここ
 },

npmで実行

npm run generate-client

おわりに

FastAPIとReactを使用して、OpenAPIでエンドポイントを自動生成する方法を紹介しました。@hey-api/openapi-tsを活用することで、APIクライアントの生成が簡単に行え、開発効率が向上します。また、FastAPIがOpenAPIをネイティブにサポートしているため、最新のAPI仕様に基づいた開発が可能です。これにより、バックエンドとフロントエンド間の連携がスムーズになり、プロジェクトの開発がより快適になるでしょう。ぜひ、この手順を参考にして、自身のプロジェクトに役立ててください。Happy Coding!

参考文献

株式会社XronotechPublication

福岡でシステム開発を行うXronotechの公式アカウントです。 Webアプリやスマホアプリを開発しています。