alova-wormhole-usage

Alova OpenAPI 連携

クライアント側での使用方法については、alova-client スキルを参照してください。 サーバー側（Node/Bun/Deno）については、alova-server スキルを参照してください。

Alova は @alova/wormhole を通じて OpenAPI/Swagger の仕様と連携し、API リクエスト関数と TypeScript の型を自動生成します。

ワークフロー

Install → Create alova.config → Run alova gen → Customize alova instance → Use generated APIs

Alova の設定

設定ファイル

対応している形式：

• alova.config.cjs：CommonJS 設定ファイル
• alova.config.js：ESModule 設定ファイル
• alova.config.ts：TypeScript 設定ファイル

alova init コマンドを使用して、設定テンプレートをすばやく作成できます。

import { defineConfig } from '@alova/wormhole';

export default defineConfig({
  // API generation settings array
  generator: [
    {
      // OpenAPI file URL or local path
      input: 'http://localhost:3000/openapi.json',

      // Output path
      output: 'src/api',

      // Platform type (swagger)
      platform: 'swagger',

      // Plugin configuration
      plugins: [],

      // Response data media type (default: application/json)
      responseMediaType: 'application/json',

      // Request body media type (default: application/json)
      bodyMediaType: 'application/json',

      // API version (default: auto)
      version: 'auto',

      // Code type: auto/ts/typescript/module/commonjs
      type: 'auto',

      // Global API export name (default: Apis)
      global: 'Apis',

      // Global mount object (default: globalThis)
      globalHost: 'globalThis',

      // Filter/transform API interface functions
      handleApi: (apiDescriptor) => apiDescriptor,
    },
  ],

  // Auto-update configuration
  autoUpdate: true, // or { launchEditor: true, interval: 5 * 60 * 1000 }
});

defineConfig には、より柔軟な設定を可能にする同期関数または非同期関数も指定できます。

プリセット Wormhole プラグイン

プラグイン	説明	ドキュメント
rename	API 関数名とパラメーター名を変更します。camelCase/snake_case に対応します	ドキュメント
tagModifier	API タグ名を変更します	ドキュメント
payloadModifier	API パラメーターの型を追加・削除・変更します	ドキュメント
filterApi	URL とタグの一致条件で API をフィルタリングします	ドキュメント
apifox	Apifox プロジェクトを自動インポートします	ドキュメント
importType	カスタマイズが必要な型を除外します	ドキュメント

使用例：

import { rename, tagModifier } from '@alova/wormhole/plugin';

export default defineConfig({
  generator: [
    {
      plugins: [
        rename({ style: 'camelCase' }),
        tagModifier({ ... })
      ]
    }
  ]
});

handleApi フック

API 設定をカスタマイズするために使用します。各 API の生成前に呼び出されます。パラメーター名、型、戻り値の型を変更できます。

注意：apiDescriptor パラメーターには、OpenAPI ファイル内の各 API に関する情報が含まれています。詳細については、OpenAPI Spec Operation Object を参照してください。

関数名を変更する（snake_case → camelCase）：

handleApi: (apiDescriptor) => {
  apiDescriptor.operationId = apiDescriptor.operationId.replace(/_([a-z])/g, (match, group) =>
    group.toUpperCase()
  );
  return apiDescriptor;
};

タグを変更する：

handleApi: (apiDescriptor) => {
  if (apiDescriptor.url.includes('/user')) {
    apiDescriptor.tags = ['userTag'];
  }
  return apiDescriptor;
};

API をフィルタリングする：

handleApi: (apiDescriptor) => {
  // Return falsy value to filter this API
  if (!apiDescriptor.path.startsWith('/user')) {
    return;
  }
  return apiDescriptor;
};

レスポンスデータ型の生成を変更する：

handleApi: (apiDescriptor) => {
  apiDescriptor.responses = apiDescriptor.responses?.properties?.data;
  return apiDescriptor;
};

生成データを変更する場合は、handleApi よりも Wormhole プラグインの使用を推奨します。プラグインを使うとロジックが簡潔になり、設定順に実行されます。

機能とリファレンスドキュメント

機能	リファレンス
インストールとセットアップ	references/INSTALLATION
CLI の使用方法（alova gen、alova init）	references/CLI
プログラム API（generate、readConfig）	references/PROGRAMMATIC-API
alova インスタンスのカスタマイズ（index.ts）	references/ALOVA-INSTANCE
トラブルシューティング	references/TROUBLESHOOTING