alova-wormhole-usage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Alova OpenAPI Integration

Alova OpenAPI 集成

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.

客户端使用方法，请查看
alova-client
技能。服务端（Node/Bun/Deno）使用方法，请查看
alova-server
技能。

Alova 通过

@alova/wormhole

与OpenAPI/Swagger规范集成，可自动生成API请求函数和TypeScript类型。

Workflow

工作流程

plaintext

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

plaintext

安装 → 创建alova.config → 运行alova gen → 自定义Alova实例 → 使用生成的API

Alova Configuration

Alova 配置

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.

支持的格式：

```
alova.config.cjs
```
: CommonJS配置文件
```
alova.config.js
```
: ESModule配置文件
```
alova.config.ts
```
: TypeScript配置文件

使用

alova init

命令快速创建配置模板。

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

export default defineConfig({
  // API生成设置数组
  generator: [
    {
      // OpenAPI文件URL或本地路径
      input: 'http://localhost:3000/openapi.json',

      // 输出路径
      output: 'src/api',

      // 平台类型（swagger）
      platform: 'swagger',

      // 插件配置
      plugins: [],

      // 响应数据媒体类型（默认：application/json）
      responseMediaType: 'application/json',

      // 请求体媒体类型（默认：application/json）
      bodyMediaType: 'application/json',

      // API版本（默认：自动）
      version: 'auto',

      // 代码类型：auto/ts/typescript/module/commonjs
      type: 'auto',

      // 全局API导出名称（默认：Apis）
      global: 'Apis',

      // 全局挂载对象（默认：globalThis）
      globalHost: 'globalThis',

      // 过滤/转换API接口函数
      handleApi: (apiDescriptor) => apiDescriptor,
    },
  ],

  // 自动更新配置
  autoUpdate: true, // 或 { launchEditor: true, interval: 5 * 60 * 1000 }
});

defineConfig
也可接受同步或异步函数，以支持更动态的配置。

Preset Wormhole Plugins

预设Wormhole插件

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({ ... })
      ]
    }
  ]
});

插件名称	说明	文档链接
`rename`	重命名API函数和参数名称，支持小驼峰/下划线命名格式	文档
`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({ ... })
      ]
    }
  ]
});

The handleApi Hook

handleApi钩子

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.

用于自定义API配置，在每个API生成前调用。可修改参数名称、类型或返回类型。

注意：

apiDescriptor

参数包含OpenAPI文件中每个API的信息。详情请参考OpenAPI规范操作对象。

重命名函数（下划线命名→小驼峰命名）:

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) => {
  // 返回假值以过滤该API
  if (!apiDescriptor.path.startsWith('/user')) {
    return;
  }
  return apiDescriptor;
};

修改响应数据类型生成:

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

优先使用Wormhole插件而非

handleApi

来修改生成的数据。插件可简化逻辑，并按配置顺序执行。

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

功能	参考链接
安装与设置	references/INSTALLATION
CLI使用方法（ `alova gen` 、 `alova init` ）	references/CLI
程序化API（ `generate` 、 `readConfig` ）	references/PROGRAMMATIC-API
自定义Alova实例（ `index.ts` ）	references/ALOVA-INSTANCE
故障排查	references/TROUBLESHOOTING