refactor(generator): 重构生成器相关代码

- 将 modules 重命名为 documents，更准确地反映其含义
- 优化 Generator 类的结构和逻辑
- 更新 Logger 类的输出格式
- 调整 Printer 类，增加 nodeName 属性
- 更新相关类型定义

Author: cloudcome

src/cli.ts

@@ -43,8 +43,8 @@ const { defineConfig } = require('openapi-axios');
  * @ref https://github.com/FrontEndDev-org/openapi-axios
  */
 module.exports = defineConfig({
-  modules: {
-    '.petStore3': 'https://petstore3.swagger.io/api/v3/openapi.json'
+  documents: {
+    'petStore3': 'https://petstore3.swagger.io/api/v3/openapi.json'
   },
 });`.trim()}\n`,
       );

src/generator/Generator.ts

@@ -22,7 +22,7 @@ export class Generator extends Emitter<GeneratorEmits> {
   static defaults: StrictGeneratorOptions = {
     cwd: process.cwd(),
     dest: '/src/apis',
-    modules: {},
+    documents: {},
   };
 
   options: StrictGeneratorOptions;
@@ -32,7 +32,7 @@ export class Generator extends Emitter<GeneratorEmits> {
   }
 
   async generate() {
-    const entries = Object.entries(this.options.modules);
+    const entries = Object.entries(this.options.documents);
     const count = entries.length;
     const payload: GeneratorPayload = { count };
     this.emit('start', payload);
@@ -41,7 +41,7 @@ export class Generator extends Emitter<GeneratorEmits> {
       let index = 0;
       for (const [name, module] of entries) {
         const openAPI: OpenAPIOptions = isString(module) ? { document: module } : module;
-        await this.#generateOpenAPI(index, count, name, openAPI);
+        await this.#generateOpenAPI({ index, count, name }, openAPI);
         index++;
       }
     }
@@ -54,12 +54,12 @@ export class Generator extends Emitter<GeneratorEmits> {
     this.emit('end', payload);
   }
 
-  async #generateOpenAPI(index: number, count: number, module: string, openAPIOptions: OpenAPIOptions) {
+  async #generateOpenAPI({ index, count, name }: { index: number; count: number; name: string }, openAPIOptions: OpenAPIOptions) {
     const { cwd, dest, ...globalPrinter } = this.options;
-    const { document, fileName = `${module}.ts`, ...scopePrinter } = openAPIOptions;
+    const { document, fileName = `${name}.ts`, ...scopePrinter } = openAPIOptions;
     const mainFile = path.join(cwd, dest, fileName);
-    const typeFile = path.join(cwd, dest, fileName.replace(/\.ts$/, '.type.ts'));
-    const schemaFile = path.join(cwd, dest, fileName.replace(/\.ts$/, '.schema.ts'));
+    const typeFile = mainFile.replace(/\.ts$/, '.type.ts');
+    const schemaFile = mainFile.replace(/\.ts$/, '.schema.ts');
 
     // 1. 参数合并
     const printerOptions = Object.assign({}, globalPrinter, scopePrinter);
@@ -69,11 +69,11 @@ export class Generator extends Emitter<GeneratorEmits> {
       dest,
       ...printerOptions,
     };
-    const makePayload = (step: GeneratingStage): GeneratingPayload => ({
+    const makePayload = (stage: GeneratingStage): GeneratingPayload => ({
       index,
       count,
-      module,
-      stage: step,
+      name,
+      stage,
       options,
       file: mainFile,
     });
@@ -87,7 +87,7 @@ export class Generator extends Emitter<GeneratorEmits> {
     // 3. 输出
     this.emit('process', makePayload('printing'));
     const printer = new Printer(openAPIV3Document, printerOptions);
-    const { type, main, schema } = printer.print({ module, cwd, mainFile, typeFile, schemaFile });
+    const { type, main, schema } = printer.print({ document: name, cwd, mainFile, typeFile, schemaFile });
 
     // 4. 写入
     this.emit('process', makePayload('writing'));

src/generator/Logger.ts

@@ -1,37 +1,45 @@
 /* eslint-disable no-console */
-import type { GeneratorEmits } from './types';
+import type { GeneratingStage, GeneratorEmits } from './types';
 import path from 'node:path';
 import chalk from 'chalk';
 
+const stateOrders: Record<GeneratingStage, number> = {
+  reading: 1,
+  printing: 2,
+  writing: 3,
+  generated: 4,
+};
+
 export class Logger {
   pipeStartEvent(...[payload]: GeneratorEmits['start']) {
-    console.log(chalk.greenBright('▶'), `即将处理 ${payload.count} 个 openAPI 文档`);
+    console.log(chalk.magenta('▶'), `即将处理 ${payload.count} 个 openAPI 文档`);
   }
 
   pipeProcessEvent(...[payload]: GeneratorEmits['process']) {
     const width = payload.count.toString().length;
     const step = (payload.index + 1).toString().padStart(width, '0');
+    const order = stateOrders[payload.stage];
 
     console.log(
-      chalk.cyanBright('▷'),
-      chalk.yellowBright(`${step}/${payload.count}`),
-      payload.module,
+      chalk.magenta('▷'),
+      chalk.yellow(`[${step}/${payload.count}]`),
+      chalk.cyan(`<${payload.name}>`),
       payload.stage,
-      payload.stage === 'generated' ? path.relative(payload.options.cwd, payload.file) : '',
+      chalk.green(payload.stage === 'generated' ? path.relative(payload.options.cwd, payload.file) : ''),
     );
   }
 
   pipeEndEvent(...[payload]: GeneratorEmits['end']) {
-    console.log(chalk.greenBright('■'), '处理完成');
+    console.log(chalk.magenta('■'), chalk.green('处理完成'));
   }
 
   pipeErrorEvent(...[err]: GeneratorEmits['error']) {
-    console.log(chalk.redBright('●'), '处理失败');
-    console.log(chalk.redBright(err.message));
+    console.log(chalk.magenta('●'), '处理失败');
+    console.log(chalk.red(err.message));
   }
 
   pipeConfigError(err: Error) {
-    console.log(chalk.redBright('○'), '配置错误');
-    console.log(chalk.redBright(err.message));
+    console.log(chalk.magenta('○'), '配置错误');
+    console.log(chalk.red(err.message));
   }
 }

src/generator/types.ts

@@ -35,9 +35,9 @@ export type GeneratorOptions = PrinterOptions & {
   prettierOptions?: Options;
 
   /**
-   * openapi 模块配置
+   * openapi 文档配置
    */
-  modules: Record<string, OpenAPIOptions | string>;
+  documents: Record<string, OpenAPIOptions | string>;
 };
 export type StrictGeneratorOptions = RequiredWith<GeneratorOptions, 'cwd' | 'dest'>;
 
@@ -50,7 +50,7 @@ export interface GeneratorPayload {
 export interface GeneratingPayload {
   index: number;
   count: number;
-  module: string;
+  name: string;
   stage: GeneratingStage;
   options: GeneratingOptions;
   file: string;

src/printer/index.ts

@@ -65,7 +65,7 @@ type WithId<T> = T & {
   nodeId: string;
   namedId?: string;
 };
-type SchemaInfo = WithId<{ position: 'root' | 'anchor'; schema: OpenApiLatest_Schema; typeName: string }>;
+type SchemaInfo = WithId<{ position: 'root' | 'anchor'; schema: OpenApiLatest_Schema; typeName: string; nodeName: string }>;
 type RequestBodyInfo = WithId<{ requestBody: OpenApiLatest_Request }>;
 type ParameterInfo = WithId<{ parameter: OpenApiLatest_Parameter }>;
 type ResponseInfo = WithId<{ response: OpenApiLatest_Response }>;
@@ -147,6 +147,7 @@ export class Printer {
           schema,
           nodeId,
           namedId,
+          nodeName: name,
         };
         this.#tryRegisterAnchors({ namedId, nodeId, typeName }, schema);
 
@@ -238,6 +239,7 @@ export class Printer {
         namedId: anchorNamedId,
         typeName: anchorTypeName,
         schema,
+        nodeName: anchorId,
       };
 
       this.named.setRefType(anchorId, anchorTypeName);
@@ -353,10 +355,11 @@ export class Printer {
     } = this.document.info;
     const { externalDocs } = this.document;
     const { name, email, url } = contact || {};
+
     const jsDoc = new JsDoc();
-    const { module } = this.configs;
-    if (module)
-      jsDoc.addComments({ module });
+    const { document } = this.configs;
+    document && jsDoc.addComments({ document });
+
     const extDoc = JsDoc.printExternalDoc(externalDocs);
     jsDoc.addComments({
       title,
@@ -413,14 +416,15 @@ export class Printer {
   }
 
   #printSchema(
-    { schema, nodeId, namedId, typeName }: SchemaInfo,
+    { schema, nodeId, nodeName, typeName }: SchemaInfo,
   ) {
     if (isUndefined(typeName)) {
       throw new Error(`未发现 schema 引用：${nodeId}`);
     }
 
     const { comments, type } = this.schemata.print(schema);
     const jsDoc = new JsDoc();
+    jsDoc.addComments({ name: nodeName });
     jsDoc.addComments(comments);
     this.schemaVars.set(typeName, {
       position: 'component',
@@ -578,7 +582,7 @@ export class Printer {
 
     const jsDoc = new JsDoc(this.document.tags);
     const comments = JsDoc.fromOperation(operation);
-    const { module } = this.configs;
+    const { document: module } = this.configs;
 
     if (module)
       jsDoc.addComments({ module });

src/printer/types.ts

@@ -119,9 +119,9 @@ export interface PrinterOptions {
 
 export interface PrinterConfigs {
   /**
-   * 表明当前 API 所在的模块
+   * 文档名称
    */
-  module?: string;
+  document?: string;
 
   /**
    * file cwd