@bitstack/ng-query-codegen-openapi 0.0.30

package/src/generators/common-types-generator.ts

@@ -0,0 +1,33 @@
+/**
+ * 產生 CommonTypeFile
+ */
+export function generateCommonTypesFile() {
+
+  return `/* eslint-disable */
+// [Warning] Generated automatically - do not edit manually
+ 
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  observe?: 'body' | 'events' | 'response';
+  responseType?: 'arraybuffer' | 'blob' | 'json' | 'text';
+  reportProgress?: boolean;
+  withCredentials?: boolean;
+  timeout?: number;
+}
+
+export interface QueryConfig {
+    refetchOnMountOrArgChange?: boolean|number,
+    keepUnusedDataFor?: number,
+}
+
+export type IRestFulEndpointsQueryReturn<TVariables> = TVariables extends void ? 
+  void | {fetchOptions?: RequestOptions;config?: QueryConfig;}: 
+  {
+      variables: TVariables;
+      fetchOptions?: RequestOptions;
+      config?: QueryConfig;
+  };
+`;
+
+}
+

package/src/generators/component-schema-generator.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+
+
+/**
+ * 產生 component-schema.ts 內容
+ * @param interfaces
+ */
+export function generateComponentSchemaFile(interfaces: Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>) {
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+  
+  const resultFile = ts.createSourceFile(
+    'component-schema.ts',
+    '',
+    ts.ScriptTarget.Latest,
+    false,
+    ts.ScriptKind.TS
+  );
+
+  // 分析接口內容以找出需要從 shared-types 導入的類型
+  return `/* eslint-disable */
+// [Warning] Generated automatically - do not edit manually 
+    
+${Object.values(interfaces).map(i => printer.printNode(ts.EmitHint.Unspecified, i, resultFile)).join('\n')}
+`
+}

package/src/generators/do-not-modify-generator.ts

@@ -0,0 +1,27 @@
+/**
+ * 產生 DO_NOT_MODIFY.md 說明檔案
+ * 
+ * 此檔案用於提醒開發者不要修改產生器生成的程式碼
+ */
+export function generateDoNotModifyFile(): string {
+  return `# 請勿修改此資料夾
+
+⚠️ **重要提醒：請勿修改此資料夾中的任何檔案**
+
+此資料夾中的所有檔案都是透過程式碼產生器自動產生的。任何手動修改的內容在下次重新產生時都將會被覆蓋。
+
+## 如何修改這些檔案？
+
+如果您需要修改這些檔案的內容，請：
+
+1. 修改相對應的設定檔案或模板
+2. 重新執行程式碼產生器
+3. 讓產生器自動更新這些檔案
+
+## 產生器相關資訊
+
+這些檔案是由 @bitstack/ng-query-codegen-openapi 產生器所建立。
+
+如有疑問，請參考專案文件或聯繫開發團隊。
+`;
+}

package/src/generators/index-generator.ts

@@ -0,0 +1,11 @@
+import type { GenerationOptions } from '../types';
+
+export function generateIndexFile(groupKey: string, options: GenerationOptions) {
+  const { groupKey: optionsGroupKey } = options;
+  
+
+  return `export * from './types';
+export * from './api.service';
+export * from './query.service';
+`;
+}

package/src/generators/query-service-generator.ts

@@ -0,0 +1,108 @@
+import type { GenerationOptions } from '../types';
+
+export function generateQueryServiceFile(endpointInfos: Array<{
+  operationName: string;
+  argTypeName: string;
+  responseTypeName: string;
+  isQuery: boolean;
+  verb: string;
+  path: string;
+  queryKeyName: string;
+  queryParams: any[];
+  pathParams: any[];
+  isVoidArg: boolean;
+  summary: string;
+}>, options: GenerationOptions) {
+
+  const { groupKey, refetchOnMountOrArgChange = 60 } = options;
+  
+  // 確定服務名稱 - 使用 groupKey 如果有提供的話
+  const queryServiceName = groupKey ?
+    `${groupKey.charAt(0).toUpperCase() + groupKey.slice(1)}QueryService` :
+    'QueryService';
+  
+  const apiServiceName = groupKey ? 
+    `${groupKey.charAt(0).toUpperCase() + groupKey.slice(1)}ApiService` :
+    'ApiService';
+
+  // 分別處理 Query 和 Mutation 方法
+  const queryMethods = endpointInfos
+    .filter(info => info.isQuery)
+    .map(info => `
+  /**
+   * ${info.summary}
+   */
+  ${info.operationName}Query(${info.argTypeName !== 'VoidApiArg' ? `args: IRestFulEndpointsQueryReturn<${info.argTypeName}>` : ''}): Observable<QueryState<${info.responseTypeName}>> {
+    return this.ntkQuery.query<${info.responseTypeName}, ${info.argTypeName !== 'VoidApiArg' ? `IRestFulEndpointsQueryReturn<${info.argTypeName}>` : 'void'}>({
+      queryKey: [ECacheKeys.${info.queryKeyName}${info.argTypeName !== 'VoidApiArg' ? ', args.variables' : ''}],
+      queryFn: () => {
+        return this.apiService.${info.operationName}(${info.argTypeName !== 'VoidApiArg' ? 'args' : ''});
+      },
+      fetchOptions: args?.fetchOptions,
+      config: args?.config,
+    })${info.argTypeName !== 'VoidApiArg' ? '(args)' : '()'};
+  }`).join('');
+
+  const mutationMethods = endpointInfos
+    .filter(info => !info.isQuery)
+    .map(info => `
+  /**
+   * ${info.summary}
+   */
+  ${info.operationName}Mutation(): MutationResponse<${info.responseTypeName}, {
+    variables: ${info.argTypeName !== 'VoidApiArg' ? info.argTypeName : 'void'};
+    fetchOptions?: RequestOptions;
+  }, HttpErrorResponse> {
+    return this.ntkQuery.mutation<${info.responseTypeName}, ${info.argTypeName !== 'VoidApiArg' ? `IRestFulEndpointsQueryReturn<${info.argTypeName}>` : 'void'}, HttpErrorResponse>({
+      endpointName: '${info.operationName}',
+      mutationFn: (${info.argTypeName !== 'VoidApiArg' ? 'args' : ''}) => {
+        return this.apiService.${info.operationName}(${info.argTypeName !== 'VoidApiArg' ? 'args' : ''});
+      },
+    });
+  }`).join('');
+
+  const lazyQueryMethods = endpointInfos
+    .filter(info => info.isQuery)
+    .map(info => `
+  /**
+   * ${info.summary}
+   */
+  ${info.operationName}LazyQuery(): {
+    trigger: (${info.argTypeName !== 'VoidApiArg' ? `args: IRestFulEndpointsQueryReturn<${info.argTypeName}>, ` : ''}options?: { skipCache?: boolean }) => Observable<${info.responseTypeName}>
+  } {
+    return {
+      trigger: (${info.argTypeName !== 'VoidApiArg' ? 'args, ' : ''}options = {}) => {
+        const { skipCache = true } = options;
+        if (!skipCache) {
+          const cachedResult = this.ntkQuery.getQueryCache<${info.responseTypeName}>([ECacheKeys.${info.queryKeyName}${info.argTypeName !== 'VoidApiArg' ? ', args.variables' : ''}]);
+          if (cachedResult) {
+            return cachedResult;
+          }
+        }
+        return this.apiService.${info.operationName}(${info.argTypeName !== 'VoidApiArg' ? 'args' : ''});
+      }
+    };
+  }`).join('');
+
+  return `/* eslint-disable */
+// [Warning] Generated automatically - do not edit manually 
+  
+import {Injectable, inject} from '@angular/core';
+import {Observable} from 'rxjs';
+import {HttpErrorResponse} from '@angular/common/http';
+import {NtkQueryService, MutationState, QueryState, MutationResponse} from '@core/ntk-query';
+import {ECacheKeys} from '../cache-keys';
+import {${apiServiceName}} from './api.service';
+import {IRestFulEndpointsQueryReturn, RequestOptions} from '../common-types';
+import {${endpointInfos.map(info => ` ${info.argTypeName}, ${info.responseTypeName}`).join(',')}} from './types';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class ${queryServiceName} {
+  private apiService = inject(${apiServiceName});
+  private ntkQuery = inject(NtkQueryService);
+${queryMethods}${mutationMethods}${lazyQueryMethods}
+}
+`;
+}

package/src/generators/types-generator.ts

@@ -0,0 +1,285 @@
+import ts from 'typescript';
+import type { GenerationOptions } from '../types';
+
+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 function generateTypesFile(
+  endpointInfos: EndpointInfo[], 
+  _options: GenerationOptions,
+  schemaInterfaces?: Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration>,
+  operationDefinitions?: any[]
+) {
+
+  // 生成 import 語句
+  let importStatement = `/* eslint-disable */
+// [Warning] Generated automatically - do not edit manually 
+  
+`;
+  
+  // 檢查是否需要引入 schema.ts
+  const hasSchemaTypes = schemaInterfaces && Object.keys(schemaInterfaces).length > 0;
+  if (hasSchemaTypes) {
+    importStatement += `import * as Schema from "../schema";\n`;
+  }
+  
+  importStatement += '\n';
+  
+  // 收集所有需要的類型定義
+  const typeDefinitions: string[] = [];
+  
+  // 注意：不再在 types.ts 中重複生成 schema 類型
+  // schema 類型已經在 schema.ts 中生成，這裡直接使用 Schema.* 引用
+  
+  // 無論是否有 schema，都要生成 endpoint 特定的 Req/Res 類型
+  const endpointTypes: string[] = [];
+  
+  // 為每個端點生成 Req/Res 類型
+  endpointInfos.forEach(endpoint => {
+    // 使用 endpoint 中提供的準確類型名稱
+    const reqTypeName = endpoint.argTypeName;
+    const resTypeName = endpoint.responseTypeName;
+    
+    // 生成 Request 類型（總是生成）
+    if (reqTypeName) {
+      const requestTypeContent = generateRequestTypeContent(endpoint, operationDefinitions);
+      if (requestTypeContent.trim() === '' || requestTypeContent.includes('TODO') || requestTypeContent.includes('[key: string]: any')) {
+        // 如果沒有實際內容，使用 void
+        endpointTypes.push(
+          `export type ${reqTypeName} = void;`,
+          ``
+        );
+      } else {
+        // 有實際內容，使用 type 定義
+        endpointTypes.push(
+          `export type ${reqTypeName} = {`,
+          requestTypeContent,
+          `};`,
+          ``
+        );
+      }
+    }
+    
+    // 生成 Response 類型（總是生成）
+    if (resTypeName) {
+      const responseTypeContent = generateResponseTypeContent(endpoint, operationDefinitions);
+      if (responseTypeContent.trim() === '' || responseTypeContent.includes('TODO') || responseTypeContent.includes('[key: string]: any')) {
+        // 如果沒有實際內容，使用 void
+        endpointTypes.push(
+          `export type ${resTypeName} = void;`,
+          ``
+        );
+      } else {
+        // 有實際內容，使用 type 定義
+        endpointTypes.push(
+          `export type ${resTypeName} = {`,
+          responseTypeContent,
+          `};`,
+          ``
+        );
+      }
+    }
+  });
+  
+  if (endpointTypes.length > 0) {
+    typeDefinitions.push(endpointTypes.join('\n'));
+  }
+  
+  // 如果沒有任何類型定義，至少添加一些基本說明
+  if (typeDefinitions.length === 0) {
+    typeDefinitions.push(
+      `// 此檔案用於定義 API 相關的類型`,
+      `// 類型定義會根據 OpenAPI Schema 自動生成`,
+      ``
+    );
+  }
+  
+  return importStatement + typeDefinitions.join('\n\n');
+}
+
+/**
+ * 生成 Request 類型的內容
+ */
+function generateRequestTypeContent(endpoint: EndpointInfo, operationDefinitions?: any[]): string {
+  const properties: string[] = [];
+  
+  // 如果有 query 參數
+  if (endpoint.queryParams && endpoint.queryParams.length > 0) {
+    endpoint.queryParams.forEach(param => {
+      const optional = param.required ? '' : '?';
+      const paramType = getTypeFromParameter(param);
+      properties.push(`  ${param.name}${optional}: ${paramType};`);
+    });
+  }
+  
+  // 如果有 path 參數
+  if (endpoint.pathParams && endpoint.pathParams.length > 0) {
+    endpoint.pathParams.forEach(param => {
+      const optional = param.required ? '' : '?';
+      const paramType = getTypeFromParameter(param);
+      properties.push(`  ${param.name}${optional}: ${paramType};`);
+    });
+  }
+  
+  // 如果有 request body（從 operationDefinitions 中獲取）
+  const operationDef = operationDefinitions?.find(op => {
+    // 嘗試多種匹配方式
+    return op.operation?.operationId === endpoint.operationName ||
+           op.operation?.operationId === endpoint.operationName.toLowerCase() ||
+           // 也嘗試匹配 verb + path 組合
+           (op.verb === endpoint.verb.toLowerCase() && op.path === endpoint.path);
+  });
+  
+  if (operationDef?.operation?.requestBody) {
+    const requestBody = operationDef.operation.requestBody;
+    const content = requestBody.content;
+    
+    // 處理不同的 content types
+    const jsonContent = content['application/json'];
+    const formContent = content['multipart/form-data'] || content['application/x-www-form-urlencoded'];
+    
+    if (jsonContent?.schema) {
+      const bodyType = getTypeFromSchema(jsonContent.schema);
+      properties.push(`  body: ${bodyType};`);
+    } else if (formContent?.schema) {
+      const bodyType = getTypeFromSchema(formContent.schema);
+      properties.push(`  body: ${bodyType};`);
+    } else {
+      properties.push(`  body?: any; // Request body from OpenAPI`);
+    }
+  }
+  
+  // 如果沒有任何參數，返回空內容（將由調用方處理為 void）
+  if (properties.length === 0) {
+    return ''; // 返回空字串，讓調用方決定使用 void
+  }
+  
+  return properties.join('\n');
+}
+
+/**
+ * 生成 Response 類型的內容
+ */
+function generateResponseTypeContent(endpoint: EndpointInfo, operationDefinitions?: any[]): string {
+  const properties: string[] = [];
+  
+  // 嘗試從 operationDefinitions 中獲取響應結構
+  const operationDef = operationDefinitions?.find(op => {
+    // 嘗試多種匹配方式
+    return op.operation?.operationId === endpoint.operationName ||
+           op.operation?.operationId === endpoint.operationName.toLowerCase() ||
+           // 也嘗試匹配 verb + path 組合
+           (op.verb === endpoint.verb.toLowerCase() && op.path === endpoint.path);
+  });
+  
+  if (operationDef?.operation?.responses) {
+    // 檢查 200 響應
+    const successResponse = operationDef.operation.responses['200'] || 
+                           operationDef.operation.responses['201'];
+    
+    if (successResponse?.content) {
+      const jsonContent = successResponse.content['application/json'];
+      if (jsonContent?.schema) {
+        const responseProps = parseSchemaProperties(jsonContent.schema);
+        properties.push(...responseProps);
+      } else {
+        properties.push(`  // Success response from OpenAPI`);
+        properties.push(`  data?: any;`);
+      }
+    }
+  }
+  
+  // 如果沒有響應定義，返回空內容（將由調用方處理為 void）
+  if (properties.length === 0) {
+    return ''; // 返回空字串，讓調用方決定使用 void
+  }
+  
+  return properties.join('\n');
+}
+
+/**
+ * 解析 OpenAPI schema 的 properties 並生成 TypeScript 屬性定義
+ */
+function parseSchemaProperties(schema: any): string[] {
+  const properties: string[] = [];
+  
+  if (schema.type === 'object' && schema.properties) {
+    const required = schema.required || [];
+    
+    Object.entries(schema.properties).forEach(([propName, propSchema]: [string, any]) => {
+      const isRequired = required.includes(propName);
+      const optional = isRequired ? '' : '?';
+      const propType = getTypeFromSchema(propSchema);
+      const description = propSchema.description ? ` // ${propSchema.description}` : '';
+      
+      properties.push(`  ${propName}${optional}: ${propType};${description}`);
+    });
+  }
+  
+  return properties;
+}
+
+/**
+ * 從 OpenAPI schema 獲取 TypeScript 類型
+ */
+function getTypeFromSchema(schema: any): string {
+  if (!schema) return 'any';
+  
+  // 處理 $ref 引用，使用 Schema.TypeName 格式
+  if (schema.$ref) {
+    const refPath = schema.$ref;
+    if (refPath.startsWith('#/components/schemas/')) {
+      const typeName = refPath.replace('#/components/schemas/', '');
+      return `Schema.${typeName}`;
+    }
+  }
+  
+  switch (schema.type) {
+    case 'string':
+      if (schema.enum) {
+        return schema.enum.map((val: string) => `"${val}"`).join(' | ');
+      }
+      return 'string';
+    case 'number':
+    case 'integer':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'array':
+      const itemType = schema.items ? getTypeFromSchema(schema.items) : 'any';
+      return `${itemType}[]`;
+    case 'object':
+      if (schema.properties) {
+        // 如果有具體的屬性定義，生成內聯對象類型
+        const props = Object.entries(schema.properties).map(([key, propSchema]: [string, any]) => {
+          const required = schema.required || [];
+          const optional = required.includes(key) ? '' : '?';
+          const type = getTypeFromSchema(propSchema);
+          return `${key}${optional}: ${type}`;
+        }).join('; ');
+        return `{ ${props} }`;
+      }
+      return 'any';
+    default:
+      return 'any';
+  }
+}
+
+/**
+ * 從參數定義中獲取 TypeScript 類型
+ */
+function getTypeFromParameter(param: any): string {
+  if (!param.schema) return 'any';
+  return getTypeFromSchema(param.schema);
+}

package/src/generators/utils-generator.ts

@@ -0,0 +1,33 @@
+import ts from 'typescript';
+
+
+/**
+ * 產生 Utils function 內容
+ * @param interfaces
+ */
+export function generateUtilsFile() {
+
+  // 分析接口內容以找出需要從 shared-types 導入的類型
+  return `/* eslint-disable */
+// [Warning] Generated automatically - do not edit manually 
+    
+/**
+* Clear undefined in object
+*/
+export function withoutUndefined(obj?: Record<string, any>) {
+  if(typeof obj === 'undefined') return;
+  return Object.fromEntries(
+      Object.entries(obj).filter(([_, v]) => v !== undefined && v !== null)
+  );
+}
+
+`
+}
+
+/**
+ * 大寫底線字串 轉 小駝峰
+ * @param str
+ */
+export function toCamelCase(str: string): string {
+  return str.toLowerCase().replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+import { UnifiedCodeGenerator, type UnifiedGenerationOptions, type UnifiedGenerationResult } from './services/unified-code-generator';
+
+export type { OutputFilesConfig, ConfigFile } from './types';
+
+
+/**
+ * 產生 Endpoints - 直接使用統一代碼生成器
+ * @param options - 端點生成選項
+ */
+export async function generateEndpoints(options: UnifiedGenerationOptions): Promise<string | void> {
+  const generator = new UnifiedCodeGenerator(options);
+
+  const result = await generator.generateAll();
+  
+  if (!result.success) {
+    if (result.errors.length > 0) {
+      throw result.errors[0];
+    }
+  }
+  return;
+}