株式会社 CoeFont でフロントエンドエンジニアをしている uzimaru です。
OpenAPI を使ったコード生成ツールには、openapi-generator や openapi-ts があると思いますが、弊社のフロントエンドで利用している kubb について紹介しようと思います。
kubb とは？
kubb とは OpenAPI を使って様々なクライアントに変換するためのツールです。
kubb は、OpenAPI Schema を元にコード生成を行うツールですが、最大の特徴は plugin システムを活用して様々なコードを生成できる点です。
plugin は公式からいくつか提供されており、以下のようなものがあります
これらの対象に対して、plugin を使うことで柔軟にコード生成をすることが出来ます。
弊社では、msw, Faker.js のコード生成をしてテストで利用しています。
kubb の基本的な使い方
kubb の概要がわかったところで、実際にどのように使うのかを見ていきましょう。以下に基本的な導入手順を紹介します。
今回は、msw のハンドラーと Faker.js のダミーデータを作成するためのコードを生成してみます。
1. インストール
kubb 本体と必要な plugin をインストールします
pnpm add @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-faker @kubb/plugin-msw
2. 設定ファイルの作成
kubb の設定ファイルを作成します。
まずは必要最低限の設定です。
import { defineConfig } from '@kubb/core'
export default defineConfig(() => {
return {
root: '.',
input: {
path: './petStore.yaml',
},
output: {
path: './src/gen',
},
plugins: [],
}
})
この設定ファイルをベースに必要な plugin の設定を追加していきます。
kubb は plugin が他の plugin で生成したファイルを参照するものがあるので、生成したいコードの plugin の他にいくつかの plugin の設定もする必要があります。
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'
export default defineConfig(() => {
return {
root: '.',
input: {
path: './petStore.yaml',
},
output: {
path: './src/gen',
},
plugins: [
pluginOas({
validate: true,
output: {
path: './json',
},
contentType: 'application/json',
}),
pluginTs({
output: {
path: './types',
},
enumType: 'literal',
unknownType: 'unknown',
}),
pluginFaker({
output: {
path: './mocks',
},
}),
pluginMsw({
output: {
path: './handlers',
banner: '// @ts-nocheck',
},
handlers: true,
parser: 'faker',
}),
],
}
})
plugin の具体的な説明は省略しますが、 @kubb/plugin-oas で OpenAPI から各種 plugin で利用する json を生成し、@kubb/plugin-ts で生成した json から TypeScript の型を生成、@kubb/plugin-faker で json を元にダミーデータを作成する関数を作り、@kubb/plugin-msw で生成された Faker.js の関数を使って msw の handler が生成されるという流れになっています。
各 plugin も柔軟に設定することができます。
他のツールとの違い
最初にも書いた通り、OpenAPI を使ってコードの自動生成をする場合は openapi-generator や openapi-ts といったツールもあります。
ですが、これらのツールは特定の対象に対してのコード生成はできるのですが、複数の対象に対してコードを生成することには対応していません。
弊社では API Client として openapi-ts を使っていたのですが、msw の handler を OpenAPI を使って作成したいというモチベーションがあったため kubb を使うという選択をしました。
kubb のデメリット
フロントエンドで OpenAPI を利用するモチベーションとして API Client を自動生成するためという目的が一般的に高いと思いますが、弊社ではまだ openapi-ts を利用した Client を使っています。
この理由として、@kubb/plugin-client が axios ベースのものであるということと各エンドポイント事に関数を作成するという点があります。
API リクエストに fetch を利用したかったということと、API Client は小さいコードにしたかったため openapi-ts を利用した Client を使い続けるという選択をしました。
プロジェクトによっては zod を使って API のレスポンスの検証をしたいというモチベーションもあると思うので、@kubb/plugin-client を使った Client の生成はいいと思います。
まとめ
kubb は plugin を活用することで、柔軟で強力なコード生成が可能になります。
独自の plugin を作成することで、特定のニーズに合わせてカスタマイズ可能なので気になる方はぜひ使ってみてください。
Discussion