feat(generator): 添加 OpenAPI schema 生成功能

- 在 Generator 中增加 schema 文件生成逻辑
- 在 Reader 中添加错误收集功能
- 修改 migrations 中的 migrate 函数，支持多版本 OpenAPI 文档- 在 PrinterConfigs 中添加 writeSchema 配置项，用于控制是否生成 schema

Author: cloudcome

src/generator/Generator.ts

@@ -1,4 +1,5 @@
 import type { PrintResult } from '../printer/types';
+import type { OpenAPILatest } from '../types/openapi';
 import type {
   GeneratingOptions,
   GeneratingPayload,
@@ -15,6 +16,7 @@ import process from 'node:process';
 import { Emitter } from 'strict-event-emitter';
 import { normalizeError } from 'try-flatten';
 import { Printer } from '../printer';
+import { OpenAPIVersion } from '../types/openapi';
 import { isString } from '../utils/type-is';
 import { Reader } from './Reader';
 
@@ -60,6 +62,11 @@ export class Generator extends Emitter<GeneratorEmits> {
     const mainFile = path.join(cwd, dest, fileName);
     const typeFile = mainFile.replace(/\.ts$/, '.type.ts');
     const zodFile = mainFile.replace(/\.ts$/, '.zod.ts');
+    const schemaFiles: Record<OpenAPIVersion, string> = {
+      [OpenAPIVersion.V2_0]: mainFile.replace(/\.ts$/, '.v2_0.json'),
+      [OpenAPIVersion.V3_0]: mainFile.replace(/\.ts$/, '.v3_0.json'),
+      [OpenAPIVersion.V3_1]: mainFile.replace(/\.ts$/, '.v3_1.json'),
+    };
 
     // 1. 参数合并
     const printerOptions = Object.assign({}, globalPrinter, scopePrinter);
@@ -82,11 +89,11 @@ export class Generator extends Emitter<GeneratorEmits> {
     this.emit('process', makePayload('reading'));
     const reader = new Reader();
     reader.cwd = cwd;
-    const openAPIV3Document = await reader.read(document);
+    const migrated = await reader.read(document);
 
     // 3. 输出
     this.emit('process', makePayload('printing'));
-    const printer = new Printer(openAPIV3Document, printerOptions);
+    const printer = new Printer(migrated.at(-1)!.document! as OpenAPILatest.Document, printerOptions);
     const { type, main, zod } = printer.print({ document: name, cwd, mainFile, typeFile, zodFile });
 
     // 4. 写入
@@ -100,6 +107,15 @@ export class Generator extends Emitter<GeneratorEmits> {
       this.#writePrintResult('zod', zodFile, zod);
     }
 
+    if (printerOptions.writeSchema) {
+      migrated.forEach(({ version, document, errors }) => {
+        this.#writePrintResult(`schema@${version}`, schemaFiles[version], {
+          code: JSON.stringify(document, null, 2),
+          errors,
+        });
+      });
+    }
+
     this.emit('process', makePayload('generated'));
   }
 

src/generator/Reader.ts

@@ -15,15 +15,17 @@ export class Reader {
     const source = await this._read(document);
     const config = await createConfig({});
     const { problems, bundle } = await bundleFromString({ config, source });
+    const errors: string[] = [];
 
     if (problems.length) {
-      console.warn(`[parse] 发现了 ${problems.length} 处错误，请检查文档，可能会出现非预期错误`);
       problems.forEach((p) => {
-        console.warn(p.message);
+        errors.push(p.message);
       });
     }
 
-    return migrate(bundle.parsed);
+    const migrated = migrate(bundle.parsed);
+    migrated[0].errors.push(...errors);
+    return migrated;
   }
 
   private async _read(document: AcceptDocument): Promise<string> {

src/migrations/index.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIAll, OpenAPILatest } from '../types/openapi';
+import type { OpenAPIAll, OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from '../types/openapi';
 import { OpenAPIVersion } from '../types/openapi';
 import { migrate_2_0To3_0 } from './openapi-2_0';
 import { migrate_3_0To3_1 } from './openapi-3_0';
@@ -23,16 +23,29 @@ const migrations = [
   //
   { from: OpenAPIVersion.V2_0, migrate: migrate_2_0To3_0 },
   { from: OpenAPIVersion.V3_0, migrate: migrate_3_0To3_1 },
+  { from: OpenAPIVersion.V3_1 },
 ];
 
+export interface MigratedV2_0 { version: OpenAPIVersion.V2_0; document: OpenAPIV2.Document; errors: string[] }
+export interface MigratedV3_0 { version: OpenAPIVersion.V3_0; document: OpenAPIV3.Document; errors: string[] }
+export interface MigratedV3_1 { version: OpenAPIVersion.V3_1; document: OpenAPIV3_1.Document; errors: string[] }
+
 export function migrate(openapi: OpenAPIAll.Document) {
-  return migrations.reduce((acc, { from, migrate }) => {
+  const migrated: Array<MigratedV2_0 | MigratedV3_0 | MigratedV3_1> = [];
+
+  migrations.reduce((acc, { from, migrate }) => {
     if (detectVersion(acc) === from) {
       // eslint-disable-next-line ts/ban-ts-comment
-      // @ts-ignore
-      return migrate(acc);
+      // @ts-expect-error
+      const result = migrate?.(acc) || acc;
+      // eslint-disable-next-line ts/ban-ts-comment
+      // @ts-expect-error
+      migrated.push({ version: from, document: acc, errors: [] });
+      return result;
     }
 
     return acc;
-  }, openapi) as OpenAPILatest.Document;
+  }, openapi);
+
+  return migrated;
 }

src/printer/types.ts

@@ -132,6 +132,11 @@ export interface PrinterOptions {
    * 是否需要在运行时验证接口的出入参
    */
   runtimeValidate?: boolean;
+
+  /**
+   * 是否生成 schema
+   */
+  writeSchema?: boolean;
 }
 
 export interface PrinterConfigs {