安装与配置

安装

npm i wormajs -D

yarn add wormajs -D

pnpm add wormajs -D

bun add wormajs -D

初始化

worma init

此命令在项目根目录创建 worma.config.js（也支持 .cjs、.mjs 或 .ts 扩展名），默认配置了 alova 模板和 aiDoc 插件：

import { defineConfig } from "wormajs";
import { alova } from "wormajs/plugin";
import { aiDoc } from "wormajs/plugin";

export default defineConfig({
  generator: [
    {
      input: "https://api.example.com/openapi.json",
      output: "src/api",
      plugins: [alova(), aiDoc()],
    },
  ],
});

init 也可通过 -T, --template 参数指定其他初始模板：

worma init -T axios
worma init --template ky
worma init -T fetch -t typescript

worma.config.js 完整配置

import { defineConfig } from "wormajs";
import { rename, aiDoc } from "wormajs/plugin";
import { alova, swagger } from "wormajs/plugin";

export default defineConfig({
  generator: [
    {
      output: "src/api",
      docComment: true,
      responseMediaType: "application/json",
      bodyMediaType: "application/json",
      serverName: "用户服务",
      plugins: [
        swagger("https://api.example.com/openapi.json"),
        alova(),
        aiDoc(),
        rename({ getUserInfo: "fetchUserProfile" }),
      ],
    },
  ],
});

配置项速览

字段	类型	必填	默认值	说明
`input`	`string \| string[]`	是	—	OpenAPI 文档地址，数组时同时请求所有 URL
`output`	`string`	否	由模板决定	输出目录
`docComment`	`boolean`	否	`true`	是否生成文档注释，设为 `false` 可提高性能
`responseMediaType`	`string \| string[]`	否	`'application/json'`	响应 MediaType，可设数组依次指向
`bodyMediaType`	`string \| string[]`	否	`'application/json'`	请求体 MediaType，可设数组依次指向
`serverName`	`string`	否	文档 `info.title`	多文档时的自定义服务名称，用于侧边栏展示
`plugins`	`ApiPlugin[]`	是	—	插件数组（模板也通过 plugin 的 getTemplate hook 设置）
`performance`	`PerformanceConfig`	否	—	性能配置

更多插件配置请查看内置插件。

多数据源配置

在 generator 数组中配置多个项，可以从不同 OpenAPI 文档生成到不同目录：

import { defineConfig } from "wormajs";
import { alova, axios } from "wormajs/plugin";
import { aiDoc } from "wormajs/plugin";

export default defineConfig({
  generator: [
    {
      input: "https://user-service.example.com/openapi.json",
      output: "src/api/user-service",
      serverName: "用户服务",
      plugins: [alova(), aiDoc()],
    },
    {
      input: "https://order-service.example.com/openapi.json",
      output: "src/api/order-service",
      serverName: "订单服务",
      plugins: [axios(), aiDoc()],
    },
  ],
});

多数据源时，建议为每个 generator 设置 serverName，便于 VSCode 扩展侧边栏分组以及 AI Skill 文档按服务分类。

多地址 fallback

input 支持 string[] 数组，同时访问每个 URL，返回第一个成功的数据：

defineConfig({
  generator: [
    {
      input: [
        "https://primary-server.com/openapi.json",
        "https://fallback-server.com/openapi.json",
      ],
      output: "./src/api",
      plugins: [alova()],
    },
  ],
});

Apifox 数据源

如果团队使用 Apifox 管理接口文档，可以直接从 Apifox 项目拉取 OpenAPI 数据，无需手动导出文件或填写 input 字段：

import { defineConfig } from "wormajs";
import { alova } from "wormajs/plugin";
import { aiDoc, apifox } from "wormajs/plugin";

export default defineConfig({
  generator: [
    {
      output: "src/api",
      serverName: "用户服务",
      plugins: [
        apifox({
          projectId: "your-project-id",
          apifoxToken: "your-api-token",
        }),
        alova(),
        aiDoc(),
      ],
    },
  ],
});

使用 apifox 插件后不再需要设置 input 字段，插件会自动从 Apifox 拉取最新的 OpenAPI 文档。更多用法（按标签筛选、指定版本等）请查看平台拉取器。

简易配置

纯文本格式，每行一个 OpenAPI 文档地址，可选携带模板与编码助手（agent）：

# 主服务，默认 alova 模板（不生成 AI 文档）
https://api.example.com/v1/openapi.json

# 管理后台，使用 axios 模板，安装 AI Skill 到 cursor
admin=https://api.admin.com/openapi.json, axios, cursor

# 文件服务，使用 fetch 模板，安装 AI Skill 到 cursor 和 claude-code
public/files=https://api.files.com/openapi.json, fetch, cursor, claude-code

行格式为：[outputKey=]url[, template][, agent]

outputKey（可选）：自定义输出目录，省略时按 src/api、src/api2… 递增。
template（可选）：模板类型，取值 alova / axios / fetch / ky，省略默认为 alova。
agent（可选）：要安装 AI Skill 的编码助手，以英文逗号或中文逗号 ， 分隔，可指定多个（自动去重）。

.wormarc 模式下 aiDoc 插件仅在行内指定了 agent 时才会被添加；未指定 agent 的行只生成对应模板代码，不会生成或安装 AI Skill 文档。

若想在 worma.config 中复用个人编码助手偏好，可结合 parseAgentFile 从 .wormaagent.local 读取（详见 AI 文档生成器）。

同时存在 .wormarc 和 worma.config 时，worma.config 优先级更高。

安装与配置

On this page