插件 API

关于插件系统概述和内置插件列表，请参阅插件系统。

createPlugin

创建类型安全的插件工厂函数。

import { createPlugin } from "wormajs";

const myPlugin = createPlugin((options: { key: string }) => ({
  name: "my-plugin",
  beforeCodeGenerate({ data }) {
    data.config.customKey = options.key;
  },
}));

// 使用
defineConfig({
  generator: [
    {
      plugins: [myPlugin({ key: "value" })],
    },
  ],
});

ApiPlugin

type MaybePromise<T> = T | Promise<T>;

type ReportProgress = (progress: number, message?: string) => void;

interface ApiPlugin {
  name?: string;

  /** ① 配置阶段：可修改 config */
  config?: (
    params: ConfigHookParams,
  ) => MaybePromise<GeneratorConfig | undefined | null | void>;

  /** ② 规范解析前：拿到原始规范文本，可返回新字符串替换后再解析 */
  beforeSpecParse?: (params: BeforeSpecParseHookParams) => MaybePromise<string | undefined | null | void>;

  /** ③ OpenAPI 解析后：可修改 document */
  specParsed?: (
    params: SpecParsedHookParams,
  ) => MaybePromise<OpenAPIDocument | undefined | null | void>;

  /** ④ 获取模板路径 */
  getTemplate?: (
    params: GetTemplateHookParams,
  ) => MaybePromise<TemplateConfigResult | undefined | null | void>;

  /** ⑤ 渲染前：注入/修改 templateData */
  beforeCodeGenerate?: (
    params: BeforeCodeGenerateHookParams,
  ) => MaybePromise<void>;

  /** ⑥ 每个文件写盘前：可修改单个文件内容 */
  beforeFileWrite?: (params: BeforeFileWriteHookParams) => MaybePromise<string>;

  /** ⑦ 所有文件写盘完成后 */
  codeGenerated?: (params: CodeGeneratedHookParams) => MaybePromise<void>;

  /** ⑧ Handlebars 实例创建时：注册自定义 helper 或 partial */
  onHandlebarsCreated?: (
    params: OnHandlebarsCreatedHookParams,
  ) => MaybePromise<void>;
}

钩子参数类型

ConfigHookParams

interface ConfigHookParams {
  config: GeneratorConfig;
  projectPath: string;
  reportProgress: ReportProgress;
}

BeforeSpecParseHookParams

beforeSpecParse 在规范文件（OpenAPI/Swagger 的 JSON 或 YAML 文本）取回之后、解析之前触发，params.spec 即原始规范文本字符串。

转换规范文件内容：钩子可以返回一个新的字符串来替换待解析的规范文本，返回的字符串会作为后续解析（含 JSON/YAML 识别、Swagger 2.0 → OpenAPI 3.0 转换）的输入。若不返回值（或返回非字符串），则保持原始文本不变。多个插件的 beforeSpecParse 会依次串联执行——前一个插件的返回结果作为后一个插件的 spec 入参。

常见用途：修复非法/不规范的原始规范文本、注入或删改字段、在解析前做字符串级别的替换等。

interface BeforeSpecParseHookParams {
  config: Readonly<GeneratorConfig>;
  /** 原始规范文本（JSON 或 YAML），解析前的字符串内容 */
  spec: string;
  projectPath: string;
  reportProgress: ReportProgress;
}

示例：解析前替换规范文本内容。

import { createPlugin } from "wormajs/plugin";

const patchSpecPlugin = createPlugin(() => ({
  name: "patch-spec",
  beforeSpecParse({ spec }) {
    // spec 是原始规范文本，返回新字符串即可替换后再解析
    return spec.replace(/"nullable":\s*"true"/g, '"nullable": true');
  },
}));

SpecParsedHookParams

interface SpecParsedHookParams {
  config: Readonly<GeneratorConfig>;
  document: OpenAPIDocument;
  projectPath: string;
  reportProgress: ReportProgress;
}

GetTemplateHookParams

interface GetTemplateHookParams {
  config: Readonly<GeneratorConfig>;
  projectPath: string;
  reportProgress: ReportProgress;
}

返回 TemplateConfigResult：

interface TemplateConfigResult {
  /** 模板路径（相对或绝对，相对是相对于 process.cwd()） */
  path: string;
}

BeforeCodeGenerateHookParams

interface BeforeCodeGenerateHookParams {
  config: Readonly<GeneratorConfig>;
  data: TemplateData;
  projectPath: string;
  reportProgress: ReportProgress;
}

直接修改 params.data 注入数据，不再返回值。

BeforeFileWriteHookParams

interface BeforeFileWriteHookParams {
  config: Readonly<GeneratorConfig>;
  data: TemplateData;
  filePath: string;
  content: string;
  projectPath: string;
  reportProgress: ReportProgress;
  /** 模板文件元数据 */
  meta: {
    templateType?: "tag" | "api";
    tag?: string;
    api?: string;
  };
}

返回修改后的文件内容字符串。

CodeGeneratedHookParams

interface CodeGeneratedHookParams {
  config: Readonly<GeneratorConfig>;
  data: TemplateData;
  /** 所有生成文件的路径（不含内容） */
  filePaths: string[];
  /** 绝对输出目录 */
  outputDir: string;
  projectPath: string;
  error?: Error;
  reportProgress: ReportProgress;
}

OnHandlebarsCreatedHookParams

interface OnHandlebarsCreatedHookParams {
  hbs: typeof import("handlebars");
  config: Readonly<GeneratorConfig>;
  projectPath: string;
  reportProgress: ReportProgress;
}

插件 API

On this page