czh-api 1.0.2 → 1.0.4

package/dist/core/parser.js

@@ -13,22 +13,83 @@ function addSchemaWithDependencies(name, module, allSchemas) {
     }
     const schema = allSchemas[name];
     if (!schema) {
+        console.warn(`警告: Schema "${name}" 未找到，跳过此引用`);
         return; // Schema not found
     }
     module.schemas[name] = schema;
-    // Recursively add dependencies
-    JSON.stringify(schema, (key, value) => {
-        if (key === '$ref' && typeof value === 'string') {
-            const depName = getSchemaName(value);
-            addSchemaWithDependencies(depName, module, allSchemas);
+    // Recursively add dependencies with error handling
+    try {
+        JSON.stringify(schema, (key, value) => {
+            if (key === '$ref' && typeof value === 'string') {
+                const depName = getSchemaName(value);
+                if (depName && allSchemas[depName]) {
+                    addSchemaWithDependencies(depName, module, allSchemas);
+                }
+                else {
+                    console.warn(`警告: 依赖 Schema "${depName}" 未找到，跳过此引用`);
+                }
+            }
+            return value;
+        });
+    }
+    catch (error) {
+        console.warn(`警告: 处理 Schema "${name}" 的依赖时出错:`, error);
+    }
+}
+function toCamelCase(str) {
+    return str
+        .split('/')
+        .filter(p => p)
+        .map((part, index) => {
+        const cleaned = part.replace(/[^a-zA-Z0-9]/g, '');
+        if (index === 0) {
+            return cleaned.charAt(0).toLowerCase() + cleaned.slice(1);
         }
-        return value;
-    });
+        return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+    })
+        .join('');
 }
-function getModuleName(path) {
+function getModuleName(path, pathPrefixes = []) {
+    // 尝试匹配配置的路径前缀
+    for (const prefix of pathPrefixes) {
+        if (path.startsWith(prefix.path)) {
+            // 获取前缀后的路径部分
+            const remainingPath = path.substring(prefix.path.length);
+            const parts = remainingPath.split('/').filter(p => p && !p.startsWith('{'));
+            // 确定包名
+            const packageName = prefix.packageName || toCamelCase(prefix.path);
+            // 如果有二级路径，使用二级路径作为子模块
+            if (parts.length > 0 && parts[0]) {
+                return `${packageName}/${parts[0]}`;
+            }
+            // 如果没有二级路径，直接使用包名
+            return packageName;
+        }
+    }
+    // 如果没有匹配到配置的前缀，使用默认逻辑
     const parts = path.split('/').filter(p => p && !p.startsWith('{'));
     return parts[0] || 'default';
 }
+function convertOpenApiTypeToTypeScript(openApiType) {
+    if (!openApiType)
+        return 'any';
+    switch (openApiType) {
+        case 'integer':
+            return 'number';
+        case 'object':
+            return 'any';
+        case 'array':
+            return 'any[]';
+        case 'boolean':
+            return 'boolean';
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        default:
+            return 'any';
+    }
+}
 function extractJsdocParamsFromSchema(schema, allSchemas) {
     var _a;
     const params = [];
@@ -45,11 +106,58 @@ function extractJsdocParamsFromSchema(schema, allSchemas) {
     if (targetSchema === null || targetSchema === void 0 ? void 0 : targetSchema.properties) {
         for (const propName in targetSchema.properties) {
             const prop = targetSchema.properties[propName];
-            // 调试: 打印出当前处理的属性
-            // console.log(`正在处理属性: ${propName}`, '值为:', prop);
+            let propType = 'any';
+            // 处理 anyOf 数组 (FastAPI 常用的联合类型)
+            if (prop.anyOf && Array.isArray(prop.anyOf)) {
+                const types = prop.anyOf.map(item => {
+                    if (isReferenceObject(item)) {
+                        return getSchemaName(item.$ref);
+                    }
+                    else {
+                        const itemSchema = item;
+                        // 处理 null 类型 (在 OpenAPI 中可能以不同方式表示)
+                        if (itemSchema.type === 'null' ||
+                            itemSchema.type === undefined && itemSchema.nullable === true ||
+                            JSON.stringify(itemSchema) === '{"type":"null"}' ||
+                            Object.keys(itemSchema).length === 0) {
+                            return 'null';
+                        }
+                        return convertOpenApiTypeToTypeScript(itemSchema.type);
+                    }
+                }).filter(type => type && type !== ''); // 只过滤掉空字符串，保留 any
+                if (types.length > 0) {
+                    propType = types.join(' | ');
+                }
+            }
+            // 处理 oneOf 数组
+            else if (prop.oneOf && Array.isArray(prop.oneOf)) {
+                const types = prop.oneOf.map(item => {
+                    if (isReferenceObject(item)) {
+                        return getSchemaName(item.$ref);
+                    }
+                    else {
+                        const itemSchema = item;
+                        // 处理 null 类型 (在 OpenAPI 中可能以不同方式表示)
+                        if (itemSchema.type === 'null' ||
+                            itemSchema.type === undefined && itemSchema.nullable === true ||
+                            JSON.stringify(itemSchema) === '{"type":"null"}' ||
+                            Object.keys(itemSchema).length === 0) {
+                            return 'null';
+                        }
+                        return convertOpenApiTypeToTypeScript(itemSchema.type);
+                    }
+                }).filter(type => type && type !== ''); // 只过滤掉空字符串，保留 any
+                if (types.length > 0) {
+                    propType = types.join(' | ');
+                }
+            }
+            // 处理普通类型
+            else if (prop.type) {
+                propType = convertOpenApiTypeToTypeScript(prop.type);
+            }
             params.push({
                 name: propName,
-                type: (prop === null || prop === void 0 ? void 0 : prop.type) || 'any',
+                type: propType,
                 description: (prop === null || prop === void 0 ? void 0 : prop.description) || '',
                 required: (_a = targetSchema.required) === null || _a === void 0 ? void 0 : _a.includes(propName)
             });
@@ -75,10 +183,11 @@ function getModuleNameFromPackage(operation) {
  * @param api The bundled OpenAPI document.
  * @param excludePaths Paths to exclude (by prefix).
  * @param includePaths Paths to include (by prefix). If provided, only these paths will be processed.
+ * @param pathPrefixes Path prefix configurations for custom module grouping.
  * @returns A structured representation of modules and their endpoints.
  */
-const processApi = (api, excludePaths = [], includePaths = []) => {
-    var _a, _b, _c, _d, _e, _f, _g;
+const processApi = (api, excludePaths = [], includePaths = [], pathPrefixes = []) => {
+    var _a, _b, _c, _d, _e, _f;
     const modules = {};
     const allSchemas = ((_a = api.components) === null || _a === void 0 ? void 0 : _a.schemas) || api.definitions || {};
     const moduleFunctionNames = {};
@@ -101,7 +210,7 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
             if (!operation.tags)
                 continue;
             const moduleNameFromPackage = getModuleNameFromPackage(operation);
-            const moduleName = moduleNameFromPackage || getModuleName(path);
+            const moduleName = moduleNameFromPackage || getModuleName(path, pathPrefixes);
             if (!modules[moduleName]) {
                 modules[moduleName] = {
                     name: moduleName,
@@ -129,6 +238,9 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
             let requestBodyTypeName = undefined;
             let contentType = undefined;
             const jsdocParams = [];
+            const paramsJsdocParams = [];
+            const dataJsdocParams = [];
+            const responseJsdocParams = [];
             // --- FormData Detection ---
             let isFormData = false;
             // Method 1: Check requestBody
@@ -178,12 +290,6 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
                 };
                 for (const param of operation.parameters) {
                     if (!isReferenceObject(param)) {
-                        const paramToAdd = {
-                            name: param.name,
-                            description: param.description || '',
-                            required: param.required,
-                            type: ((_c = param.schema) === null || _c === void 0 ? void 0 : _c.type) || 'any'
-                        };
                         // If the parameter's schema is a reference, expand its properties
                         if (param.in === 'query' && param.schema && isReferenceObject(param.schema)) {
                             const schemaName = getSchemaName(param.schema.$ref);
@@ -228,26 +334,32 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
                     requestBodyTypeName = typeName;
                     modules[moduleName].schemas[typeName] = formDataSchema;
                     referencedTypes.push(typeName);
-                    jsdocParams.push(...extractJsdocParamsFromSchema(formDataSchema, allSchemas));
+                    const formDataJsdoc = extractJsdocParamsFromSchema(formDataSchema, allSchemas);
+                    jsdocParams.push(...formDataJsdoc);
+                    dataJsdocParams.push(...formDataJsdoc);
                 }
                 if (Object.keys(paramsSchema.properties || {}).length > 0) {
                     requestParamsTypeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Params`;
                     modules[moduleName].schemas[requestParamsTypeName] = paramsSchema;
                     referencedTypes.push(requestParamsTypeName);
-                    jsdocParams.push(...extractJsdocParamsFromSchema(paramsSchema, allSchemas));
+                    const paramsJsdoc = extractJsdocParamsFromSchema(paramsSchema, allSchemas);
+                    jsdocParams.push(...paramsJsdoc);
+                    paramsJsdocParams.push(...paramsJsdoc);
                 }
             }
             // Handle standard Request Body
             if (operation.requestBody && !isReferenceObject(operation.requestBody) && !isFormData) {
                 const requestBody = operation.requestBody;
-                const jsonContent = (_d = requestBody.content) === null || _d === void 0 ? void 0 : _d['application/json'];
+                const jsonContent = (_c = requestBody.content) === null || _c === void 0 ? void 0 : _c['application/json'];
                 if (jsonContent === null || jsonContent === void 0 ? void 0 : jsonContent.schema) {
                     if (isReferenceObject(jsonContent.schema)) {
                         const name = getSchemaName(jsonContent.schema.$ref);
                         requestBodyTypeName = name;
                         addSchemaWithDependencies(name, modules[moduleName], allSchemas);
                         referencedTypes.push(name);
-                        jsdocParams.push(...extractJsdocParamsFromSchema(jsonContent.schema, allSchemas));
+                        const bodyJsdoc = extractJsdocParamsFromSchema(jsonContent.schema, allSchemas);
+                        jsdocParams.push(...bodyJsdoc);
+                        dataJsdocParams.push(...bodyJsdoc);
                     }
                     else {
                         // Handle inline schema (including arrays)
@@ -264,11 +376,15 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
                                     addSchemaWithDependencies(itemSchemaName, modules[moduleName], allSchemas);
                                 }
                                 else {
-                                    jsdocParams.push(...extractJsdocParamsFromSchema(schema.items, allSchemas));
+                                    const arrayJsdoc = extractJsdocParamsFromSchema(schema.items, allSchemas);
+                                    jsdocParams.push(...arrayJsdoc);
+                                    dataJsdocParams.push(...arrayJsdoc);
                                 }
                             }
                             else if (schema.type === 'object') {
-                                jsdocParams.push(...extractJsdocParamsFromSchema(schema, allSchemas));
+                                const objJsdoc = extractJsdocParamsFromSchema(schema, allSchemas);
+                                jsdocParams.push(...objJsdoc);
+                                dataJsdocParams.push(...objJsdoc);
                             }
                         }
                     }
@@ -276,26 +392,56 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
             }
             else if (isFormData && operation.requestBody && !isReferenceObject(operation.requestBody) && !requestBodyTypeName) {
                 // Handle cases where FormData is defined in requestBody but we haven't processed it yet
-                const formDataContent = (_e = operation.requestBody.content) === null || _e === void 0 ? void 0 : _e['multipart/form-data'];
+                const formDataContent = (_d = operation.requestBody.content) === null || _d === void 0 ? void 0 : _d['multipart/form-data'];
                 if (formDataContent === null || formDataContent === void 0 ? void 0 : formDataContent.schema) {
                     const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Data`;
                     requestBodyTypeName = typeName;
                     modules[moduleName].schemas[typeName] = formDataContent.schema;
                     referencedTypes.push(typeName);
-                    jsdocParams.push(...extractJsdocParamsFromSchema(formDataContent.schema, allSchemas));
+                    const formJsdoc = extractJsdocParamsFromSchema(formDataContent.schema, allSchemas);
+                    dataJsdocParams.push(...formJsdoc);
                 }
             }
             // Handle Response Body
             let responseTypeName = 'void';
             const successResponse = operation.responses['200'];
             if (successResponse) {
-                const mediaType = ((_f = successResponse.content) === null || _f === void 0 ? void 0 : _f['*/*']) || ((_g = successResponse.content) === null || _g === void 0 ? void 0 : _g['application/json']);
+                const mediaType = ((_e = successResponse.content) === null || _e === void 0 ? void 0 : _e['*/*']) || ((_f = successResponse.content) === null || _f === void 0 ? void 0 : _f['application/json']);
                 const schema = mediaType === null || mediaType === void 0 ? void 0 : mediaType.schema;
                 if (schema && isReferenceObject(schema)) {
                     const name = getSchemaName(schema.$ref);
                     responseTypeName = name;
                     addSchemaWithDependencies(name, modules[moduleName], allSchemas);
                     referencedTypes.push(name);
+                    responseJsdocParams.push(...extractJsdocParamsFromSchema(schema, allSchemas));
+                }
+                else if (schema && !isReferenceObject(schema)) {
+                    const inlineSchema = schema;
+                    if (inlineSchema.type === 'object' || inlineSchema.properties) {
+                        // Generate a named type for inline response schema
+                        const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Response`;
+                        responseTypeName = typeName;
+                        modules[moduleName].schemas[typeName] = inlineSchema;
+                        referencedTypes.push(typeName);
+                        responseJsdocParams.push(...extractJsdocParamsFromSchema(inlineSchema, allSchemas));
+                    }
+                    else if (inlineSchema.type === 'array' && inlineSchema.items) {
+                        if (isReferenceObject(inlineSchema.items)) {
+                            const itemSchemaName = getSchemaName(inlineSchema.items.$ref);
+                            // Prefer direct `ItemType[]` for array responses to avoid unnecessary alias schema compilation.
+                            responseTypeName = `${itemSchemaName}[]`;
+                            referencedTypes.push(itemSchemaName);
+                            addSchemaWithDependencies(itemSchemaName, modules[moduleName], allSchemas);
+                            responseJsdocParams.push(...extractJsdocParamsFromSchema(inlineSchema.items, allSchemas));
+                        }
+                        else {
+                            const typeName = `${functionName.charAt(0).toUpperCase() + functionName.slice(1)}Response`;
+                            responseTypeName = typeName;
+                            modules[moduleName].schemas[typeName] = inlineSchema;
+                            referencedTypes.push(typeName);
+                            responseJsdocParams.push(...extractJsdocParamsFromSchema(inlineSchema, allSchemas));
+                        }
+                    }
                 }
             }
             // Convert path to template literal string for path parameters
@@ -313,6 +459,9 @@ const processApi = (api, excludePaths = [], includePaths = []) => {
                 hasData: !!requestBodyTypeName,
                 contentType,
                 jsdocParams,
+                paramsJsdocParams,
+                dataJsdocParams,
+                responseJsdocParams,
             };
             modules[moduleName].endpoints.push(endpoint);
         }

package/dist/templates/api.hbs

@@ -10,12 +10,7 @@ export const {{functionName}} = ({{#if hasParams}}params: {{requestParamsTypeNam
   return http.request<{{responseTypeName}}>({
     url: `{{path}}`,
     method: '{{method}}',
-    {{#if hasParams}}
-    params,
-    {{/if}}
-    {{#if hasData}}
-    data,
-    {{/if}}
+    {{#if hasParams}}{{#unless (eq method 'put')}}{{#unless (eq method 'post')}}params,{{/unless}}{{/unless}}{{/if}}{{#if hasData}}data,{{/if}}
     {{#if contentType}}
     headers: { 'Content-Type': '{{contentType}}' },
     {{/if}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "czh-api",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "A CLI tool to generate TypeScript API clients from Swagger/OpenAPI documents.",
   "main": "dist/index.js",
   "bin": {
@@ -19,6 +19,7 @@
   "author": "Czh",
   "license": "ISC",
   "dependencies": {
+    "@apiture/openapi-down-convert": "^0.14.2",
     "@types/pinyin": "^2.10.2",
     "axios": "^1.10.0",
     "chalk": "^4.1.2",