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

1 はじめに
2 FastAPI側の準備
3 orvalのセットアップとコード生成
4 生成されたコードの確認
5 さいごに
6 おすすめ書籍

はじめに

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の定義さえあれば良いので処理はダミーとなっています。)

import uuid from fastapi import APIRouter, FastAPI from pydantic import BaseModel, ConfigDict from enum import StrEnum, auto from datetime import datetime from pydantic.alias_generators import to_camel app = FastAPI(title="Petstore", version="1.0.0") # --- Models --- class BaseSchema(BaseModel): """APIのリクエスト・レスポンスJSONをキャメルケースにするためのベースクラス""" model_config = ConfigDict( # フィールドをキャメルケースに変換 alias_generator=to_camel, # スネークケースも許可ための設定 # (この設定をオンにしないと、Pythonコード上でスネークケースでのインスタンス生成ができなくなってしまう) populate_by_name=True, ) class CategoryEnum(StrEnum): dogs = auto() cats = auto() birds = auto() reptiles = auto() others = auto() class Pet(BaseSchema): id: uuid.UUID name: str category: CategoryEnum photo_urls: list[str] on_sale_from: datetime | None = None # --- Endpoints --- pets_router = APIRouter(tags=["pets"]) # ここでタグを指定する @pets_router.get("/pets", response_model=list[Pet]) def list_pets(): # ダミー実装 return [ Pet( id=uuid.uuid4(), name="doggie", category=CategoryEnum.dogs, photo_urls=["http://example.com/photo1.jpg"], on_sale_from=datetime.now(), ), Pet( id=uuid.uuid4(), name="kitty", category=CategoryEnum.cats, photo_urls=["http://example.com/photo2.jpg"], on_sale_from=datetime.now(), ), ] @pets_router.get("/pets/{petId}", response_model=Pet) def get_pet_by_id(petId: uuid.UUID): # ダミー実装 return Pet( id=uuid.uuid4(), name="doggie", category=CategoryEnum.dogs, photo_urls=["http://example.com/photo1.jpg"], on_sale_from=datetime.utcnow(), ) @pets_router.post("/pets", response_model=Pet) def add_pet(pet: Pet): # ダミー実装 return pet @pets_router.put("/pets/{petId}", response_model=Pet) def update_pet(petId: uuid.UUID, pet: Pet): # ダミー実装 return pet @pets_router.delete("/pets/{petId}") def delete_pet(petId: int): # ダミー実装 pass app.include_router(pets_router)

import uuid

from fastapi import APIRouter, FastAPI

from pydantic import BaseModel, ConfigDict

from enum import StrEnum, auto

from datetime import datetime

from pydantic.alias_generators import to_camel

app = FastAPI(title="Petstore", version="1.0.0")

# --- Models ---

class BaseSchema(BaseModel):

"""APIのリクエスト・レスポンスJSONをキャメルケースにするためのベースクラス"""

model_config = ConfigDict(

# フィールドをキャメルケースに変換

alias_generator=to_camel,

# スネークケースも許可ための設定

# (この設定をオンにしないと、Pythonコード上でスネークケースでのインスタンス生成ができなくなってしまう)

populate_by_name=True,

)

class CategoryEnum(StrEnum):

dogs = auto()

cats = auto()

birds = auto()

reptiles = auto()

others = auto()

class Pet(BaseSchema):

id: uuid.UUID

name: str

category: CategoryEnum

photo_urls: list[str]

on_sale_from: datetime | None = None

# --- Endpoints ---

pets_router = APIRouter(tags=["pets"]) # ここでタグを指定する

@pets_router.get("/pets", response_model=list[Pet])

def list_pets():

# ダミー実装

return [

Pet(

id=uuid.uuid4(),

name="doggie",

category=CategoryEnum.dogs,

photo_urls=["http://example.com/photo1.jpg"],

on_sale_from=datetime.now(),

Pet(

id=uuid.uuid4(),

name="kitty",

category=CategoryEnum.cats,

photo_urls=["http://example.com/photo2.jpg"],

on_sale_from=datetime.now(),

]

@pets_router.get("/pets/{petId}", response_model=Pet)

def get_pet_by_id(petId: uuid.UUID):

# ダミー実装

return Pet(

id=uuid.uuid4(),

name="doggie",

category=CategoryEnum.dogs,

photo_urls=["http://example.com/photo1.jpg"],

on_sale_from=datetime.utcnow(),

)

@pets_router.post("/pets", response_model=Pet)

def add_pet(pet: Pet):

# ダミー実装

return pet

@pets_router.put("/pets/{petId}", response_model=Pet)

def update_pet(petId: uuid.UUID, pet: Pet):

# ダミー実装

return pet

@pets_router.delete("/pets/{petId}")

def delete_pet(petId: int):

# ダミー実装

pass

app.include_router(pets_router)

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

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

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

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

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

1	pnpm add -D orval

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

import { defineConfig } from "orval";

export default defineConfig({

petstore: {

output: {

mode: "tags-split", // タグごとにディレクトリ分割

target: "src/api/", // APIクライアントの出力先ディレクトリ

mock: true, // MSWのモックを生成

override: {

// 生成ファイルに eslint-disable コメントを追加

header: (info) => [

`Generated by orval 🍺`,

`Do not edit manually.`,

...(info.title ? [info.title] : []),

...(info.description ? [info.description] : []),

...(info.version ? [`OpenAPI spec version: ${info.version}`] : []),

"eslint-disable",

// date/date-timeの型をDateに変換

useDates: true,

// 生成される関数の名前を変更

operationName: (operation) => {

if (!operation.summary) {

throw new Error(

"Operation summary is required for generating operation names."

);

}

// summaryは「Get Pet By Id」のような形式なので、キャメルケースに変換

const pascalCase = operation.summary.replace(/\s+/g, "");

return `${pascalCase.charAt(0).toLowerCase()}${pascalCase.slice(1)}`;

// 生成後に Prettierでフォーマット

prettier: true,

input: {

// OpenAPIの取得先

target: "http://localhost:8000/openapi.json",

});

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

my-app

└── src

├── petstore.schemas.ts // APIで使用するオブジェクトやEnumの型定義

└── pets // タグごとにディレクトリが切られる

├── petstore.msw.ts // MSWモック

└── petstore.ts // APIクライアント

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

/**

* @summary Get Pet By Id

export const getPetByIdPetsPetIdGet = <TData = AxiosResponse<Pet>>(

petId: number, options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.get(

`/pets/${petId}`,options

);

}

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

{

"paths": {

"/pets/{petId}": {

"get": {

"tags": [

"pets"

"summary": "Get Pet By Id",

"operationId": "get_pet_by_id_pets__petId__get",

"parameters": [

{

"name": "petId",

"in": "path",

"required": true,

"schema": {

"type": "integer",

"title": "Petid"

}

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/Pet"

}

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

// 生成される関数の名前を変更

operationName: (operation) => {

if (!operation.summary) {

throw new Error(

"Operation summary is required for generating operation names."

);

}

// summaryは「Get Pet By Id」のような形式なので、キャメルケースに変換

const pascalCase = operation.summary.replace(/\s+/g, "");

return `${pascalCase.charAt(0).toLowerCase()}${pascalCase.slice(1)}`;

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

生成されたコードの確認

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

/* eslint-disable */

/**

* Generated by orval 🍺

* Do not edit manually.

* Petstore

* OpenAPI spec version: 1.0.0

export type CategoryEnum = typeof CategoryEnum[keyof typeof CategoryEnum];

// eslint-disable-next-line @typescript-eslint/no-redeclare

export const CategoryEnum = {

dogs: 'dogs',

cats: 'cats',

birds: 'birds',

reptiles: 'reptiles',

others: 'others',

} as const;

export interface HTTPValidationError {

detail?: ValidationError[];

}

export type PetOnSaleFrom = Date | null;

export interface Pet {

id: string;

name: string;

category: CategoryEnum;

photoUrls: string[];

onSaleFrom?: PetOnSaleFrom;

}

export type ValidationErrorLocItem = string | number;

export interface ValidationError {

loc: ValidationErrorLocItem[];

msg: string;

type: string;

}

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

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

/* eslint-disable */ /** * Generated by orval 🍺 * Do not edit manually. * Petstore * OpenAPI spec version: 1.0.0 */ import * as axios from 'axios'; import type { AxiosRequestConfig, AxiosResponse } from 'axios'; import type { Pet } from '../petstore.schemas'; /** * @summary List Pets */ export const listPets = <TData = AxiosResponse<Pet[]>>( options?: AxiosRequestConfig ): Promise<TData> => { return axios.default.get( `/pets`,options ); } /** * @summary Add Pet */ export const addPet = <TData = AxiosResponse<Pet>>( pet: Pet, options?: AxiosRequestConfig ): Promise<TData> => { return axios.default.post( `/pets`, pet,options ); } /** * @summary Get Pet By Id */ export const getPetById = <TData = AxiosResponse<Pet>>( petId: string, options?: AxiosRequestConfig ): Promise<TData> => { return axios.default.get( `/pets/${petId}`,options ); } /** * @summary Update Pet */ export const updatePet = <TData = AxiosResponse<Pet>>( petId: string, pet: Pet, options?: AxiosRequestConfig ): Promise<TData> => { return axios.default.put( `/pets/${petId}`, pet,options ); } /** * @summary Delete Pet */ export const deletePet = <TData = AxiosResponse<unknown>>( petId: number, options?: AxiosRequestConfig ): Promise<TData> => { return axios.default.delete( `/pets/${petId}`,options ); } export type ListPetsResult = AxiosResponse<Pet[]> export type AddPetResult = AxiosResponse<Pet> export type GetPetByIdResult = AxiosResponse<Pet> export type UpdatePetResult = AxiosResponse<Pet> export type DeletePetResult = AxiosResponse<unknown>

/* eslint-disable */

/**

* Generated by orval 🍺

* Do not edit manually.

* Petstore

* OpenAPI spec version: 1.0.0

import * as axios from 'axios';

import type {

AxiosRequestConfig,

AxiosResponse

} from 'axios';

import type {

Pet

} from '../petstore.schemas';

/**

* @summary List Pets

export const listPets = <TData = AxiosResponse<Pet[]>>(

options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.get(

`/pets`,options

);

}

/**

* @summary Add Pet

export const addPet = <TData = AxiosResponse<Pet>>(

pet: Pet, options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.post(

`/pets`,

pet,options

);

}

/**

* @summary Get Pet By Id

export const getPetById = <TData = AxiosResponse<Pet>>(

petId: string, options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.get(

`/pets/${petId}`,options

);

}

/**

* @summary Update Pet

export const updatePet = <TData = AxiosResponse<Pet>>(

petId: string,

pet: Pet, options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.put(

`/pets/${petId}`,

pet,options

);

}

/**

* @summary Delete Pet

export const deletePet = <TData = AxiosResponse<unknown>>(

petId: number, options?: AxiosRequestConfig

): Promise<TData> => {

return axios.default.delete(

`/pets/${petId}`,options

);

}

export type ListPetsResult = AxiosResponse<Pet[]>

export type AddPetResult = AxiosResponse<Pet>

export type GetPetByIdResult = AxiosResponse<Pet>

export type UpdatePetResult = AxiosResponse<Pet>

export type DeletePetResult = AxiosResponse<unknown>

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

さいごに

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

日	月	火	水	木	金	土
1	2	3	4	5	6	7
8	9	10	11	12	13	14
15	16	17	18	19	20	21
22	23	24	25	26	27	28
29	30

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

はじめに

FastAPI側の準備

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

生成されたコードの確認

さいごに

おすすめ書籍

フォロー

アプリ情報