kubbによるOpenAPIの柔軟なコード生成の実現

TypeScript OpenAPI tech株式会社 CoeFont でフロントエンドエンジニアをしている uzimaru です。 OpenAPI を使ったコード生成ツールには、openapi-generator や openapi-ts があると思いますが、弊社のフロントエンドで利用している kubb について紹介しようと思います。

kubb とは OpenAPI を使って様々なクライアントに変換するためのツールです。 kubb は、OpenAPI Schema を元にコード生成を行うツールですが、最大の特徴は plugin システムを活用して様々なコードを生成できる点です。 plugin は公式からいくつか提供されており、以下のようなものがあります

これらの対象に対して、plugin を使うことで柔軟にコード生成をすることが出来ます。 弊社では、msw, Faker.js のコード生成をしてテストで利用しています。

kubb の概要がわかったところで、実際にどのように使うのかを見ていきましょう。以下に基本的な導入手順を紹介します。 今回は、msw のハンドラーと Faker.js のダミーデータを作成するためのコードを生成してみます。

kubb 本体と必要な plugin をインストールします

pnpm add @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-faker @kubb/plugin-msw

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

@kubb/plugin-ts

@kubb/plugin-faker

@kubb/plugin-msw

最初にも書いた通り、OpenAPI を使ってコードの自動生成をする場合は openapi-generator や openapi-ts といったツールもあります。 ですが、これらのツールは特定の対象に対してのコード生成はできるのですが、複数の対象に対してコードを生成することには対応していません。 弊社では API Client として openapi-ts を使っていたのですが、msw の handler を OpenAPI を使って作成したいというモチベーションがあったため kubb を使うという選択をしました。

フロントエンドで OpenAPI を利用するモチベーションとして API Client を自動生成するためという目的が一般的に高いと思いますが、弊社ではまだ openapi-ts を利用した Client を使っています。 この理由として、@kubb/plugin-client が axios ベースのものであるということと各エンドポイント事に関数を作成するという点があります。 API リクエストに fetch

kubb は plugin を活用することで、柔軟で強力なコード生成が可能になります。 独自の plugin を作成することで、特定のニーズに合わせてカスタマイズ可能なので気になる方はぜひ使ってみてください。

CoeFontPublicationAI音声プラットフォーム「CoeFont（コエフォント）」の公式テックブログです。