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