alovajs/alova-wormhole-usage

Alova OpenAPI Integration

For client-side usage, see alova-client skill. For server-side (Node/Bun/Deno), see alova-server skill.

Alova integrates with OpenAPI/Swagger specs via @alova/wormhole to auto-generate API request functions and TypeScript types.

Workflow

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

Alova Configuration

Configuration File

Supported formats:

• alova.config.cjs: CommonJS configuration file
• alova.config.js: ESModule configuration file
• alova.config.ts: TypeScript configuration file

Use the alova init command to quickly create a configuration template.

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 }
});

The defineConfig can also accept a sync or async function to allow for more dynamic configuration.

Preset Wormhole Plugins

| Plugin | Description | Documentation | | ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------- | | rename | Rename API functions and parameter names, supports camelCase/snake_case | Docs | | tagModifier | Modify API tag names | Docs | | payloadModifier | Add/remove/modify API parameter types | Docs | | filterApi | Filter APIs by URL and tag matching | Docs | | apifox | Auto-import Apifox projects | Docs | | importType | Exclude types that need customization | Docs |

Usage Example:

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

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

The handleApi Hook

Used to customize API configuration. Called before each API is generated. Can modify parameter names, types, or return types.

Note: The apiDescriptor parameter contains information for each API in the OpenAPI file. For details, refer to OpenAPI Spec Operation Object.

Rename function (snake_case → camelCase):

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

Modify Tags:

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

Filter APIs:

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

Modify response data type generation:

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

Prefer using Wormhole plugins over handleApi for modifying generated data. Plugins simplify the logic and execute in configuration order.

Features & Reference Docs

| Feature | Reference | | ------------------------------------------- | ------------------------------------------------------------- | | Installation & setup | references/INSTALLATION | | CLI usage (alova gen, alova init) | references/CLI | | Programmatic API (generate, readConfig) | references/PROGRAMMATIC-API | | Customizing the alova instance (index.ts) | references/ALOVA-INSTANCE | | Troubleshooting | references/TROUBLESHOOTING |