@bitstack/ng-query-codegen-openapi 0.0.30

package/src/services/api-code-generator.ts

@@ -0,0 +1,157 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import ts from 'typescript';
+import { OpenApiParserService } from './openapi-parser-service';
+import { EndpointInfoExtractor } from './endpoint-info-extractor';
+import { generateTypesFile } from '../generators/types-generator';
+import { generateIndexFile } from '../generators/index-generator';
+import { QueryCodeGenerator } from './query-code-generator';
+import { ApiServiceGenerator } from './api-service-generator';
+import type { GenerationOptions, GenerateApiResult } from '../types';
+
+/**
+ * API 程式碼生成器 - 負責生成單一群組的 API 相關程式碼
+ * 
+ * 設計理念：
+ * - 類別化管理：使用 class 封裝邏輯
+ * - 分離關注點：將 Query 和 API 服務分開生成
+ * - 重用資源：接受外部已處理的 v3Doc，避免重複處理
+ */
+export class ApiCodeGenerator {
+  private infoExtractor: EndpointInfoExtractor;
+  private queryGenerator: QueryCodeGenerator;
+  private apiServiceGenerator: ApiServiceGenerator;
+
+  constructor(
+    private parserService: OpenApiParserService,
+    private options: GenerationOptions
+  ) {
+  
+    // // 初始化端點資訊提取器
+    this.infoExtractor = new EndpointInfoExtractor(options);
+    //
+    // 初始化分離的生成器
+    this.queryGenerator = new QueryCodeGenerator(options);
+    this.apiServiceGenerator = new ApiServiceGenerator(options);
+  }
+
+  /**
+   * 生成完整的 API 程式碼
+   */
+  async generate(): Promise<GenerateApiResult> {
+    // console.log('ApiCodeGenerator: 開始生成 API 程式碼...');
+
+    // 步驟 1: 獲取操作定義
+    const operationDefinitions = this.parserService.getOperationDefinitions(this.options.filterEndpoints);
+
+    // 步驟 2: 提取端點資訊
+    const endpointInfos = this.infoExtractor.extractEndpointInfos(operationDefinitions);
+
+
+    // 步驟 3: 生成各種內容
+    const typesContent = this.generateTypes(endpointInfos);
+    
+
+    const apiServiceContent = this.generateApiService(endpointInfos);
+    const queryServiceContent = this.generateQueryService(endpointInfos);
+    const indexContent = this.generateIndex();
+
+    // 步驟 4: 收集端點快取鍵資訊（只收集 Query 類型的端點）
+    const allEndpointCacheKeys = endpointInfos
+      .filter(info => info.isQuery) // 只收集查詢類型的端點
+      .map(info => ({
+        operationName: info.operationName,
+        queryKeyName: info.queryKeyName,
+        groupKey: this.options.groupKey || '_common'
+      }));
+
+    // 步驟 5: 收集操作名稱
+    const operationNames = endpointInfos.map(info => info.operationName);
+
+    // console.log('ApiCodeGenerator: API 程式碼生成完成');
+
+    return {
+      operationNames,
+      files: {
+        types: typesContent,
+        apiService: apiServiceContent,
+        queryService: queryServiceContent,
+        index: indexContent,
+        allEndpointCacheKeys: allEndpointCacheKeys
+      }
+    };
+  }
+
+  /**
+   * 生成 Types 檔案內容
+   */
+  private generateTypes(endpointInfos: Array<any>): string {
+    const generatorOptions = {
+      ...this.options,
+      apiConfiguration: this.options.apiConfiguration || { 
+        file: '@/store/webapi', 
+        importName: 'WebApiConfiguration' 
+      }
+    };
+
+    // 從 parser service 獲取 schema interfaces
+    const apiGen = this.parserService.getApiGenerator();
+    const schemaInterfaces = apiGen.aliases.reduce<Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>>((curr, alias) => {
+      if (ts.isInterfaceDeclaration(alias) || ts.isTypeAliasDeclaration(alias)) {
+        const name = alias.name.text;
+        return {
+          ...curr,
+          [name]: alias,
+        };
+      }
+      return curr;
+    }, {});
+
+    // 獲取操作定義以供類型生成使用
+    const operationDefinitions = this.parserService.getOperationDefinitions(this.options.filterEndpoints);
+
+    return generateTypesFile(endpointInfos, generatorOptions, schemaInterfaces, operationDefinitions);
+  }
+
+  /**
+   * 生成 API Service 檔案內容
+   */
+  private generateApiService(endpointInfos: Array<any>): string {
+    return this.apiServiceGenerator.generateApiService(endpointInfos);
+  }
+
+  /**
+   * 生成 Query Service 檔案內容
+   */
+  private generateQueryService(endpointInfos: Array<any>): string {
+    return this.queryGenerator.generateQueryService(endpointInfos);
+  }
+
+  /**
+   * 生成 Index 檔案內容
+   */
+  private generateIndex(): string {
+    const generatorOptions = {
+      ...this.options,
+      apiConfiguration: this.options.apiConfiguration || { 
+        file: '@/store/webapi', 
+        importName: 'WebApiConfiguration' 
+      }
+    };
+
+    return generateIndexFile(this.options.groupKey || '', generatorOptions);
+  }
+
+  // /**
+  //  * 獲取已解析的 parser service（供外部使用）
+  //  */
+  // getParserService(): OpenApiParserService {
+  //   return this.parserService;
+  // }
+  //
+  // /**
+  //  * 獲取端點資訊提取器（供外部使用）
+  //  */
+  // getInfoExtractor(): EndpointInfoExtractor {
+  //   return this.infoExtractor;
+  // }
+}

package/src/services/api-service-generator.ts

@@ -0,0 +1,24 @@
+import type { GenerationOptions } from '../types';
+import { generateApiServiceFile } from '../generators/api-service-generator';
+
+/**
+ * API 服務程式碼生成器 - 專門負責生成 API Service 相關程式碼
+ */
+export class ApiServiceGenerator {
+  constructor(private options: GenerationOptions) {}
+
+  /**
+   * 生成 API Service 檔案內容
+   */
+  generateApiService(endpointInfos: Array<any>): string {
+    const generatorOptions = {
+      ...this.options,
+      apiConfiguration: this.options.apiConfiguration || { 
+        file: '@/store/webapi', 
+        importName: 'WebApiConfiguration' 
+      }
+    };
+
+    return generateApiServiceFile(endpointInfos, generatorOptions);
+  }
+}

package/src/services/endpoint-info-extractor.ts

@@ -0,0 +1,119 @@
+import { capitalize, isQuery as testIsQuery } from '../utils';
+import { getOperationName, getOverrides } from '../utils/http';
+import type { OperationDefinition, GenerationOptions } from '../types';
+import { supportDeepObjects } from 'oazapfts/generate';
+
+/**
+ * 端點資訊介面
+ */
+export interface EndpointInfo {
+  operationName: string;
+  argTypeName: string;
+  responseTypeName: string;
+  isQuery: boolean;
+  verb: string;
+  path: string;
+  queryKeyName: string;
+  queryParams: any[];
+  pathParams: any[];
+  isVoidArg: boolean;
+  summary: string;
+}
+
+/**
+ * 端點資訊提取器 - 專門負責從操作定義中提取端點資訊
+ */
+export class EndpointInfoExtractor {
+  constructor(
+    private options: Pick<GenerationOptions, 'operationNameSuffix' | 'argSuffix' | 'responseSuffix' | 'queryMatch' | 'endpointOverrides'>
+  ) {}
+
+  /**
+   * 從操作定義列表提取端點資訊
+   * @param operationDefinitions - 操作定義列表
+   */
+  extractEndpointInfos(operationDefinitions: OperationDefinition[]): EndpointInfo[] {
+    return operationDefinitions.map((operationDefinition) => {
+      return this.extractSingleEndpointInfo(operationDefinition);
+    });
+  }
+
+  /**
+   * 從單一操作定義提取端點資訊
+   * @param operationDefinition - 操作定義
+   */
+  private extractSingleEndpointInfo(operationDefinition: OperationDefinition): EndpointInfo {
+    const { verb, path, operation } = operationDefinition;
+    const { operationNameSuffix = '', argSuffix = 'Req', responseSuffix = 'Res', queryMatch, endpointOverrides } = this.options;
+
+    // 獲取操作名稱
+    const operationName = getOperationName({ verb, path });
+    const finalOperationName = operationNameSuffix ? capitalize(operationName + operationNameSuffix) : operationName;
+
+    // 生成類型名稱
+    const argTypeName = capitalize(operationName + operationNameSuffix + argSuffix);
+    const responseTypeName = capitalize(operationName + operationNameSuffix + responseSuffix);
+
+    // 判斷是否為查詢類型
+    const isQuery = testIsQuery(verb, path, getOverrides(operationDefinition, endpointOverrides), queryMatch);
+    
+    // 生成查詢鍵名稱
+    const queryKeyName = `${operationName.replace(/([A-Z])/g, '_$1').toUpperCase()}`;
+
+    // 提取 OpenAPI summary
+    const summary = operation.summary || `${verb.toUpperCase()} ${path}`;
+
+    // 解析參數
+    const { queryParams, pathParams, isVoidArg } = this.extractParameters(operationDefinition);
+
+    return {
+      operationName: finalOperationName,
+      argTypeName,
+      responseTypeName,
+      isQuery,
+      verb: verb.toUpperCase(),
+      path,
+      queryKeyName,
+      queryParams,
+      pathParams,
+      isVoidArg,
+      summary
+    };
+  }
+
+  /**
+   * 提取操作的參數資訊
+   * @param operationDefinition - 操作定義
+   */
+  private extractParameters(operationDefinition: OperationDefinition) {
+    const { operation, pathItem } = operationDefinition;
+
+    // 解析參數
+    const operationParameters = this.resolveArray(operation.parameters);
+    const pathItemParameters = this.resolveArray(pathItem.parameters)
+      .filter((pp) => !operationParameters.some((op) => op.name === pp.name && op.in === pp.in));
+    
+    const allParameters = supportDeepObjects([...pathItemParameters, ...operationParameters])
+      .filter((param) => param.in !== 'header');
+
+    const queryParams = allParameters.filter(param => param.in === 'query');
+    const pathParams = allParameters.filter(param => param.in === 'path');
+
+    // 檢查是否為 void 類型參數
+    const isVoidArg = queryParams.length === 0 && pathParams.length === 0 && !operation.requestBody;
+
+    return {
+      queryParams,
+      pathParams,
+      isVoidArg
+    };
+  }
+
+  /**
+   * 解析參數陣列 (模擬 apiGen.resolveArray)
+   */
+  private resolveArray(parameters: any): any[] {
+    if (!parameters) return [];
+    return Array.isArray(parameters) ? parameters : [parameters];
+  }
+}

package/src/services/file-writer-service.ts

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDirectoryExists } from '../utils/directory';
+
+/**
+ * 檔案寫入結果
+ */
+export interface FileWriteResult {
+  path: string;
+  success: boolean;
+  error?: Error;
+}
+
+/**
+ * 檔案寫入服務 - 負責將產生的內容寫入檔案
+ */
+export class FileWriterService {
+  /**
+   * 寫入單一檔案
+   * @param filePath - 檔案路徑
+   * @param content - 檔案內容
+   */
+  async writeFile(filePath: string, content: string): Promise<FileWriteResult> {
+    try {
+      const resolvedPath = path.resolve(process.cwd(), filePath);
+      await ensureDirectoryExists(resolvedPath);
+      
+      fs.writeFileSync(resolvedPath, content);
+      
+      return {
+        path: resolvedPath,
+        success: true
+      };
+    } catch (error) {
+      return {
+        path: filePath,
+        success: false,
+        error: error as Error
+      };
+    }
+  }
+
+  /**
+   * 批次寫入多個檔案
+   * @param files - 檔案路徑與內容的對應表
+   */
+  async writeFiles(files: Record<string, string>): Promise<FileWriteResult[]> {
+    const results: FileWriteResult[] = [];
+    
+    for (const [filePath, content] of Object.entries(files)) {
+      const result = await this.writeFile(filePath, content);
+      results.push(result);
+    }
+    
+    return results;
+  }
+
+  /**
+   * 為群組寫入標準檔案結構
+   * @param groupOutputDir - 群組輸出目錄
+   * @param files - 檔案內容
+   */
+  async writeGroupFiles(
+    groupOutputDir: string,
+    files: {
+      types?: string;
+      apiService?: string;
+      queryService?: string;
+      index?: string;
+    }
+  ): Promise<FileWriteResult[]> {
+    const filesToWrite: Record<string, string> = {};
+
+    if (files.types) {
+      filesToWrite[path.join(groupOutputDir, 'types.ts')] = files.types;
+    }
+    
+    if (files.apiService) {
+      filesToWrite[path.join(groupOutputDir, 'api.service.ts')] = files.apiService;
+    }
+    
+    if (files.queryService) {
+      filesToWrite[path.join(groupOutputDir, 'query.service.ts')] = files.queryService;
+    }
+    
+    if (files.index) {
+      filesToWrite[path.join(groupOutputDir, 'index.ts')] = files.index;
+    }
+
+    return this.writeFiles(filesToWrite);
+  }
+
+  /**
+   * 寫入共享檔案
+   * @param outputDir - 輸出目錄
+   * @param sharedFiles - 共享檔案內容
+   */
+  async writeSharedFiles(
+    outputDir: string,
+    sharedFiles: {
+      commonTypes?: string;
+      cacheKeys?: string;
+      doNotModify?: string;
+      utils?: string;
+    }
+  ): Promise<FileWriteResult[]> {
+    const filesToWrite: Record<string, string> = {};
+
+    if (sharedFiles.commonTypes) {
+      filesToWrite[path.join(outputDir, 'common-types.ts')] = sharedFiles.commonTypes;
+    }
+    
+    if (sharedFiles.cacheKeys) {
+      filesToWrite[path.join(outputDir, 'cache-keys.ts')] = sharedFiles.cacheKeys;
+    }
+
+    if (sharedFiles.doNotModify) {
+      filesToWrite[path.join(outputDir, 'DO_NOT_MODIFY.md')] = sharedFiles.doNotModify;
+    }
+
+    if (sharedFiles.utils) {
+      filesToWrite[path.join(outputDir, 'utils.ts')] = sharedFiles.utils;
+    }
+
+    return this.writeFiles(filesToWrite);
+  }
+
+
+
+
+  /**
+   * 寫入共享檔案
+   * @param outputDir - 輸出目錄
+   * @param schema
+   */
+  async writeSchemaFile(
+    outputDir: string,
+    schema: string
+  ): Promise<FileWriteResult[]> {
+    const filesToWrite: Record<string, string> = {};
+
+    filesToWrite[path.join(outputDir, 'schema.ts')] = schema;
+
+    return this.writeFiles(filesToWrite);
+  }
+
+
+}

package/src/services/group-service.ts

@@ -0,0 +1,84 @@
+import camelCase from 'lodash.camelcase';
+
+/**
+ * 群組配置介面
+ */
+export interface GroupConfig {
+  outputDir: string;
+  groupKeyMatch: (path: string) => string | null;
+  filterEndpoint?: (operationName: string, path: string, groupKey: string) => boolean;
+  queryMatch?: (operationName: string) => boolean;
+}
+
+/**
+ * 群組信息介面
+ */
+export interface GroupInfo {
+  groupKey: string;
+  paths: string[];
+  outputPath: string;
+}
+
+/**
+ * 群組服務 - 負責處理 API 路徑分組
+ */
+export class GroupService {
+  /**
+   * 根據配置對路徑進行分組
+   * @param paths - API 路徑陣列
+   * @param config - 群組配置
+   */
+  groupPaths(paths: string[], config: GroupConfig): Record<string, GroupInfo> {
+    const { groupKeyMatch, outputDir } = config;
+    
+    const groupedPaths = paths.reduce((acc, path) => {
+      const rawGroupKey = groupKeyMatch(path);
+      const groupKey = rawGroupKey ? camelCase(rawGroupKey) : '_common';
+      
+      if (!acc[groupKey]) {
+        acc[groupKey] = [];
+      }
+      acc[groupKey].push(path);
+      return acc;
+    }, {} as Record<string, string[]>);
+
+    // 轉換為 GroupInfo 格式
+    const result: Record<string, GroupInfo> = {};
+    for (const [groupKey, paths] of Object.entries(groupedPaths)) {
+      result[groupKey] = {
+        groupKey,
+        paths,
+        outputPath: `${outputDir}/${groupKey}/query.service.ts`
+      };
+    }
+
+    return result;
+  }
+
+  /**
+   * 為特定群組建立篩選函數
+   * @param groupKey - 群組鍵
+   * @param config - 群組配置
+   */
+  createGroupFilter(
+    groupKey: string,
+    config: GroupConfig
+  ): (operationName: string, operationDefinition: any) => boolean {
+    return (operationName: string, operationDefinition: any) => {
+      const path = operationDefinition.path;
+
+      // 檢查路徑是否匹配當前分組
+      const pathGroupKey = camelCase(config.groupKeyMatch(path) || '');
+      if (pathGroupKey !== groupKey && (pathGroupKey || '_common') !== groupKey) {
+        return false;
+      }
+
+      // 使用 filterEndpoint 進行額外篩選
+      if (config.filterEndpoint) {
+        return config.filterEndpoint(operationName, path, groupKey);
+      }
+
+      return true;
+    };
+  }
+}

package/src/services/openapi-parser-service.ts

@@ -0,0 +1,72 @@
+import ApiGenerator from 'oazapfts/generate';
+import type { OpenAPIV3 } from 'openapi-types';
+import type { GenerationOptions } from '../types';
+import { getOperationDefinitions } from '../utils';
+
+/**
+ * OpenAPI 解析器服務 - 負責解析 OpenAPI 文檔並提取相關數據
+ */
+export class OpenApiParserService {
+  private apiGen: ApiGenerator;
+
+  constructor(
+    private v3Doc: OpenAPIV3.Document,
+    options: Partial<GenerationOptions>
+  ) {
+    this.apiGen = new ApiGenerator(v3Doc, {
+      unionUndefined: options.unionUndefined,
+      useEnumType: options.useEnumType,
+      mergeReadWriteOnly: options.mergeReadWriteOnly,
+    });
+  }
+
+  /**
+   * 初始化 - 預處理組件
+   */
+  initialize(): void {
+    if (this.apiGen.spec.components?.schemas) {
+      this.apiGen.preprocessComponents(this.apiGen.spec.components.schemas);
+      
+      // 手動為每個 schema 生成 type alias
+      Object.keys(this.apiGen.spec.components.schemas).forEach(schemaName => {
+        try {
+          this.apiGen.getRefAlias({ $ref: `#/components/schemas/${schemaName}` });
+        } catch (error) {
+          // 忽略無法生成的 schema
+        }
+      });
+    }
+  }
+
+  /**
+   * 獲取操作定義列表
+   * @param filterEndpoints - 端點過濾函數
+   */
+  getOperationDefinitions(filterEndpoints?: any) {
+    const { operationMatches } = require('../utils/http');
+    return getOperationDefinitions(this.v3Doc).filter(operationMatches(filterEndpoints));
+  }
+
+  /**
+   * 獲取 API 生成器實例
+   */
+  getApiGenerator(): ApiGenerator {
+    return this.apiGen;
+  }
+
+  /**
+   * 獲取 OpenAPI 文檔
+   */
+  getDocument(): OpenAPIV3.Document {
+    return this.v3Doc;
+  }
+
+  /**
+   * 獲取所有 schema 類型名稱
+   */
+  getSchemaTypeNames(): Set<string> {
+    const schemeTypeNames = new Set<string>();
+    // 這裡可以根據需要添加 schema 類型名稱的提取邏輯
+    return schemeTypeNames;
+  }
+}

package/src/services/openapi-service.ts

@@ -0,0 +1,61 @@
+import type { OpenAPIV3 } from 'openapi-types';
+import { getV3Doc, downloadSchemaFile } from '../utils';
+
+/**
+ * OpenAPI 服務 - 負責獲取和處理 OpenAPI 文檔
+ * 
+ * 單一職責：
+ * - 從本地文件或遠程URL獲取OpenAPI文檔
+ * - 管理文檔快取
+ * - 提供文檔基本操作方法
+ * 
+ * 設計原則：
+ * - 非收集模式：每次調用都是獨立的操作
+ * - 無副作用：不修改傳入的參數
+ * - 可測試性：所有方法都有明確的輸入輸出
+ */
+export class OpenApiService {
+  private docCache: Record<string, OpenAPIV3.Document> = {};
+
+  /**
+   * 獲取 OpenAPI 文檔
+   * @param schemaLocation - Schema 位置 (URL 或本地路徑)
+   * @param httpResolverOptions - HTTP 解析選項
+   */
+  async getDocument(
+    schemaLocation: string, 
+    httpResolverOptions?: any
+  ): Promise<OpenAPIV3.Document> {
+    if (this.docCache[schemaLocation]) {
+      return this.docCache[schemaLocation];
+    }
+
+    const doc = await getV3Doc(schemaLocation, httpResolverOptions);
+    this.docCache[schemaLocation] = doc;
+    return doc;
+  }
+
+  /**
+   * 下載遠程 Schema 文件
+   * @param remoteUrl - 遠程 URL
+   * @param localPath - 本地儲存路徑
+   */
+  async downloadSchema(remoteUrl: string, localPath: string): Promise<string> {
+    return downloadSchemaFile(remoteUrl, localPath);
+  }
+
+  /**
+   * 獲取所有 API 路徑
+   * @param doc - OpenAPI 文檔
+   */
+  getPaths(doc: OpenAPIV3.Document): string[] {
+    return Object.keys(doc.paths || {});
+  }
+
+  /**
+   * 清除快取
+   */
+  clearCache(): void {
+    this.docCache = {};
+  }
+}

package/src/services/query-code-generator.ts

@@ -0,0 +1,24 @@
+import type { GenerationOptions } from '../types';
+import { generateQueryServiceFile } from '../generators/query-service-generator';
+
+/**
+ * Query 服務程式碼生成器 - 專門負責生成 Query Service 相關程式碼
+ */
+export class QueryCodeGenerator {
+  constructor(private options: GenerationOptions) {}
+
+  /**
+   * 生成 Query Service 檔案內容
+   */
+  generateQueryService(endpointInfos: Array<any>): string {
+    const generatorOptions = {
+      ...this.options,
+      apiConfiguration: this.options.apiConfiguration || { 
+        file: '@/store/webapi', 
+        importName: 'WebApiConfiguration' 
+      }
+    };
+
+    return generateQueryServiceFile(endpointInfos, generatorOptions);
+  }
+}