czh-api 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 所有重要的版本更新都会记录在此文件中。
 
+## [1.0.5] - 2026-03-19
+
+### 修复
+- 修复 FastAPI 场景下返回类型字段被错误降级为 `any` 的问题（如 `items.$ref`、`anyOf`、`oneOf`、`allOf` 组合场景）。
+- 修复数组响应与嵌套对象类型在 fallback 生成流程中丢失字段的问题，避免出现仅有 `{ [key: string]: any }` 的空壳接口。
+- 修复 `group_ids` 等多层结构类型解析不完整的问题，支持递归解析到更深层级（如 `number[] | null`）。
+- 修复类型增强阶段对复杂类型名（数组、联合类型）处理不稳定导致的类型声明异常问题。
+
+### 改进
+- 增强 fallback 类型生成策略：优先基于 `module.schemas` 还原字段结构，再回退到 `any`，生成结果更可用。
+- 增强类型依赖收集能力：从字段类型表达式中提取嵌套引用类型并自动补齐声明。
+- 完善 README 模板示例并与当前默认模板保持一致（`api.hbs`、`index.hbs`、`types.hbs`）。
+
 ## [1.0.4] - 2026-03-19
 
 ### 修复

package/README.md

@@ -190,12 +190,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}}
@@ -209,11 +204,9 @@ export const {{functionName}} = ({{#if hasParams}}params: {{requestParamsTypeNam
 export const {{functionName}} = ({{#if hasParams}}params: {{requestParamsTypeName}}{{/if}}{{#if hasData}}{{#if hasParams}}, {{/if}}data: {{requestBodyTypeName}}{{/if}}) => {
   return request.{{#if (eq method "delete")}}del{{else}}{{method}}{{/if}}<{{responseTypeName}}>({
     url: `{{path}}`,
-    {{#if hasParams}}
-    params,
-    {{/if}}
-    {{#if hasData}}
-    data,
+    {{#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/dist/commands/build.js

@@ -48,7 +48,7 @@ function convertOpenApiTypeToTypeScript(openApiType) {
         case 'number':
             return 'number';
         default:
-            return 'any';
+            return openApiType;
     }
 }
 // 改进类型定义的辅助函数
@@ -93,6 +93,138 @@ function findInterfaceBlockRange(content, typeName) {
     }
     return null;
 }
+const TS_BUILTIN_TYPE_NAMES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
+    'object',
+    'Record',
+    'Array',
+    'Date',
+    'Promise',
+    'true',
+    'false',
+]);
+function extractTypeIdentifiers(typeExpr) {
+    if (!typeExpr)
+        return [];
+    const matches = typeExpr.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [];
+    return [...new Set(matches.filter(name => !TS_BUILTIN_TYPE_NAMES.has(name)))];
+}
+function getSchemaNameFromRef(ref) {
+    if (!ref)
+        return '';
+    return ref.split('/').pop() || '';
+}
+function resolveSchemaTypeFromModuleSchemas(schema, moduleSchemas, visitedRefs = new Set()) {
+    if (!schema)
+        return 'any';
+    if (schema.$ref) {
+        const refName = getSchemaNameFromRef(schema.$ref);
+        return refName || 'any';
+    }
+    const schemaObj = schema;
+    if (schemaObj.anyOf && Array.isArray(schemaObj.anyOf) && schemaObj.anyOf.length > 0) {
+        const types = schemaObj.anyOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+    if (schemaObj.oneOf && Array.isArray(schemaObj.oneOf) && schemaObj.oneOf.length > 0) {
+        const types = schemaObj.oneOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+    if (schemaObj.type === 'array') {
+        const itemType = resolveSchemaTypeFromModuleSchemas(schemaObj.items, moduleSchemas, visitedRefs);
+        return `${itemType || 'any'}[]`;
+    }
+    if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
+        if (schemaObj.additionalProperties === true) {
+            return 'Record<string, any>';
+        }
+        const valueType = resolveSchemaTypeFromModuleSchemas(schemaObj.additionalProperties, moduleSchemas, visitedRefs);
+        return `Record<string, ${valueType || 'any'}>`;
+    }
+    if (schemaObj.type === 'object' && schemaObj.properties && Object.keys(schemaObj.properties).length > 0) {
+        const requiredSet = new Set(schemaObj.required || []);
+        const inlineFields = Object.entries(schemaObj.properties).map(([key, value]) => {
+            const fieldType = resolveSchemaTypeFromModuleSchemas(value, moduleSchemas, visitedRefs);
+            const optional = requiredSet.has(key) ? '' : '?';
+            return `${key}${optional}: ${fieldType || 'any'}`;
+        });
+        return `{ ${inlineFields.join('; ')} }`;
+    }
+    const baseType = convertOpenApiTypeToTypeScript(schemaObj.type);
+    if (!baseType)
+        return 'any';
+    return schemaObj.nullable ? `${baseType} | null` : baseType;
+}
+function collectSchemaProperties(schema, moduleSchemas, visitedRefs = new Set()) {
+    const collected = {
+        properties: {},
+        required: new Set(),
+    };
+    if (!schema)
+        return collected;
+    if (schema.$ref) {
+        const ref = schema.$ref;
+        if (!visitedRefs.has(ref)) {
+            visitedRefs.add(ref);
+            const refName = getSchemaNameFromRef(ref);
+            const refSchema = moduleSchemas[refName];
+            if (refSchema) {
+                const nested = collectSchemaProperties(refSchema, moduleSchemas, visitedRefs);
+                Object.assign(collected.properties, nested.properties);
+                nested.required.forEach(field => collected.required.add(field));
+            }
+        }
+        return collected;
+    }
+    const schemaObj = schema;
+    if (schemaObj.allOf && Array.isArray(schemaObj.allOf)) {
+        schemaObj.allOf.forEach(item => {
+            const nested = collectSchemaProperties(item, moduleSchemas, visitedRefs);
+            Object.assign(collected.properties, nested.properties);
+            nested.required.forEach(field => collected.required.add(field));
+        });
+    }
+    if (schemaObj.properties) {
+        Object.entries(schemaObj.properties).forEach(([name, value]) => {
+            collected.properties[name] = value;
+        });
+    }
+    (schemaObj.required || []).forEach(field => collected.required.add(field));
+    return collected;
+}
+function buildInterfaceDefinitionFromModuleSchemas(typeName, moduleSchemas) {
+    const schema = moduleSchemas[typeName];
+    if (!schema)
+        return null;
+    const { properties, required } = collectSchemaProperties(schema, moduleSchemas);
+    const entries = Object.entries(properties);
+    if (entries.length === 0)
+        return null;
+    const lines = entries.map(([propName, propSchema]) => {
+        const optional = required.has(propName) ? '' : '?';
+        const propType = resolveSchemaTypeFromModuleSchemas(propSchema, moduleSchemas) || 'any';
+        const propDescription = propSchema.description || '';
+        const comment = propDescription ? ` // ${propDescription}` : '';
+        return `  ${propName}${optional}: ${propType};${comment}`;
+    });
+    return `export interface ${typeName} {\n${lines.join('\n')}\n}`;
+}
 function improveTypeDefinitions(typesContent, endpoints) {
     let improvedContent = typesContent;
     // 收集所有需要改进的类型定义
@@ -481,6 +613,7 @@ const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
                         console.log(chalk_1.default.blue(`为模块 "${moduleName}" 生成基于 JSDoc 的类型定义...`));
                         // 创建类型定义映射
                         const typeDefinitions = {};
+                        const nestedReferencedTypes = new Set();
                         // 从 endpoints 中提取类型定义
                         module.endpoints.forEach(endpoint => {
                             // 辅助函数：将 jsdoc params 转换为字段
@@ -497,6 +630,11 @@ const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
                                 else {
                                     type = convertOpenApiTypeToTypeScript(type);
                                 }
+                                extractTypeIdentifiers(type).forEach(typeName => {
+                                    if (isValidTypeIdentifier(typeName)) {
+                                        nestedReferencedTypes.add(typeName);
+                                    }
+                                });
                                 const comment = param.description ? ` // ${param.description}` : '';
                                 return `  ${param.name}${optional}: ${type};${comment}`;
                             })
@@ -533,11 +671,23 @@ ${responseFields}
                             }
                         });
                         // 为没有定义的类型添加基本定义
-                        allReferencedTypes.forEach(typeName => {
+                        const fallbackReferencedTypes = [
+                            ...new Set([
+                                ...allReferencedTypes,
+                                ...Object.keys(module.schemas || {}),
+                                ...nestedReferencedTypes,
+                            ])
+                        ];
+                        fallbackReferencedTypes.forEach(typeName => {
                             if (!isValidTypeIdentifier(typeName)) {
                                 return;
                             }
                             if (!typeDefinitions[typeName]) {
+                                const schemaBasedDefinition = buildInterfaceDefinitionFromModuleSchemas(typeName, module.schemas);
+                                if (schemaBasedDefinition) {
+                                    typeDefinitions[typeName] = schemaBasedDefinition;
+                                    return;
+                                }
                                 typeDefinitions[typeName] = `export interface ${typeName} {
   [key: string]: any;
 }`;

package/dist/core/parser.js

@@ -87,11 +87,68 @@ function convertOpenApiTypeToTypeScript(openApiType) {
         case 'number':
             return 'number';
         default:
-            return 'any';
+            return openApiType;
     }
 }
+function resolveSchemaToTypeScript(schema, allSchemas) {
+    if (!schema)
+        return 'any';
+    if (isReferenceObject(schema)) {
+        return getSchemaName(schema.$ref) || 'any';
+    }
+    if (schema.anyOf && Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        const unionTypes = schema.anyOf
+            .map(item => resolveSchemaToTypeScript(item, allSchemas))
+            .filter(Boolean);
+        if (unionTypes.length > 0) {
+            return [...new Set(unionTypes)].join(' | ');
+        }
+    }
+    if (schema.oneOf && Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+        const unionTypes = schema.oneOf
+            .map(item => resolveSchemaToTypeScript(item, allSchemas))
+            .filter(Boolean);
+        if (unionTypes.length > 0) {
+            return [...new Set(unionTypes)].join(' | ');
+        }
+    }
+    if (schema.allOf && Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        const intersectionTypes = schema.allOf
+            .map(item => resolveSchemaToTypeScript(item, allSchemas))
+            .filter(Boolean);
+        if (intersectionTypes.length > 0) {
+            return [...new Set(intersectionTypes)].join(' & ');
+        }
+    }
+    if (schema.type === 'array') {
+        const itemType = resolveSchemaToTypeScript(schema.items, allSchemas);
+        return `${itemType || 'any'}[]`;
+    }
+    if (schema.type === 'object') {
+        if (schema.properties && Object.keys(schema.properties).length > 0) {
+            const requiredSet = new Set(schema.required || []);
+            const inlineFields = Object.entries(schema.properties).map(([key, value]) => {
+                const fieldType = resolveSchemaToTypeScript(value, allSchemas);
+                const optional = requiredSet.has(key) ? '' : '?';
+                return `${key}${optional}: ${fieldType || 'any'}`;
+            });
+            return `{ ${inlineFields.join('; ')} }`;
+        }
+        if (schema.additionalProperties) {
+            if (schema.additionalProperties === true) {
+                return 'Record<string, any>';
+            }
+            const valueType = resolveSchemaToTypeScript(schema.additionalProperties, allSchemas);
+            return `Record<string, ${valueType || 'any'}>`;
+        }
+        return 'any';
+    }
+    const baseType = convertOpenApiTypeToTypeScript(schema.type);
+    const nullable = schema.nullable ? ' | null' : '';
+    return `${baseType}${nullable}`;
+}
 function extractJsdocParamsFromSchema(schema, allSchemas) {
-    var _a;
+    var _a, _b;
     const params = [];
     if (!schema)
         return params;
@@ -106,9 +163,12 @@ 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];
-            let propType = 'any';
+            let propType = resolveSchemaToTypeScript(prop, allSchemas);
+            const propDescription = isReferenceObject(prop)
+                ? (((_a = allSchemas[getSchemaName(prop.$ref)]) === null || _a === void 0 ? void 0 : _a.description) || '')
+                : ((prop === null || prop === void 0 ? void 0 : prop.description) || '');
             // 处理 anyOf 数组 (FastAPI 常用的联合类型)
-            if (prop.anyOf && Array.isArray(prop.anyOf)) {
+            if (false && prop.anyOf && Array.isArray(prop.anyOf)) {
                 const types = prop.anyOf.map(item => {
                     if (isReferenceObject(item)) {
                         return getSchemaName(item.$ref);
@@ -130,7 +190,7 @@ function extractJsdocParamsFromSchema(schema, allSchemas) {
                 }
             }
             // 处理 oneOf 数组
-            else if (prop.oneOf && Array.isArray(prop.oneOf)) {
+            else if (false && prop.oneOf && Array.isArray(prop.oneOf)) {
                 const types = prop.oneOf.map(item => {
                     if (isReferenceObject(item)) {
                         return getSchemaName(item.$ref);
@@ -152,14 +212,26 @@ function extractJsdocParamsFromSchema(schema, allSchemas) {
                 }
             }
             // 处理普通类型
-            else if (prop.type) {
-                propType = convertOpenApiTypeToTypeScript(prop.type);
+            else if (false && prop.type) {
+                const propSchema = prop;
+                if (propSchema.type === 'array' && propSchema.items) {
+                    if (isReferenceObject(propSchema.items)) {
+                        propType = `${getSchemaName(propSchema.items.$ref)}[]`;
+                    }
+                    else {
+                        const itemType = convertOpenApiTypeToTypeScript(propSchema.items.type);
+                        propType = `${itemType}[]`;
+                    }
+                }
+                else {
+                    propType = convertOpenApiTypeToTypeScript(propSchema.type);
+                }
             }
             params.push({
                 name: propName,
-                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)
+                type: propType || 'any',
+                description: propDescription,
+                required: (_b = targetSchema.required) === null || _b === void 0 ? void 0 : _b.includes(propName)
             });
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "czh-api",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A CLI tool to generate TypeScript API clients from Swagger/OpenAPI documents.",
   "main": "dist/index.js",
   "bin": {

package/src/commands/build.ts

@@ -18,8 +18,8 @@ import { compile } from 'json-schema-to-typescript';
 import { Converter } from '@apiture/openapi-down-convert';
 
 // 统一的类型转换函数
-function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
-    if (!openApiType) return 'any';
+function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
+    if (!openApiType) return 'any';
     
     switch (openApiType) {
         case 'integer':
@@ -32,12 +32,12 @@ function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string
             return 'boolean';
         case 'string':
             return 'string';
-        case 'number':
-            return 'number';
-        default:
-            return 'any';
-    }
-}
+        case 'number':
+            return 'number';
+        default:
+            return openApiType;
+    }
+}
 
 // 改进类型定义的辅助函数
 function isValidTypeIdentifier(typeName: string | undefined): boolean {
@@ -85,6 +85,176 @@ function findInterfaceBlockRange(content: string, typeName: string): { start: nu
     return null;
 }
 
+const TS_BUILTIN_TYPE_NAMES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'void',
+    'any',
+    'unknown',
+    'never',
+    'object',
+    'Record',
+    'Array',
+    'Date',
+    'Promise',
+    'true',
+    'false',
+]);
+
+function extractTypeIdentifiers(typeExpr: string | undefined): string[] {
+    if (!typeExpr) return [];
+    const matches = typeExpr.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) || [];
+    return [...new Set(matches.filter(name => !TS_BUILTIN_TYPE_NAMES.has(name)))];
+}
+
+function getSchemaNameFromRef(ref: string | undefined): string {
+    if (!ref) return '';
+    return ref.split('/').pop() || '';
+}
+
+function resolveSchemaTypeFromModuleSchemas(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
+    visitedRefs: Set<string> = new Set()
+): string {
+    if (!schema) return 'any';
+
+    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
+        const refName = getSchemaNameFromRef((schema as OpenAPIV3.ReferenceObject).$ref);
+        return refName || 'any';
+    }
+
+    const schemaObj = schema as OpenAPIV3.SchemaObject;
+
+    if (schemaObj.anyOf && Array.isArray(schemaObj.anyOf) && schemaObj.anyOf.length > 0) {
+        const types = schemaObj.anyOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+
+    if (schemaObj.oneOf && Array.isArray(schemaObj.oneOf) && schemaObj.oneOf.length > 0) {
+        const types = schemaObj.oneOf
+            .map(item => resolveSchemaTypeFromModuleSchemas(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs))
+            .filter(Boolean);
+        if (types.length > 0) {
+            return [...new Set(types)].join(' | ');
+        }
+    }
+
+    if (schemaObj.type === 'array') {
+        const itemType = resolveSchemaTypeFromModuleSchemas(
+            schemaObj.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+            moduleSchemas,
+            visitedRefs
+        );
+        return `${itemType || 'any'}[]`;
+    }
+
+    if (schemaObj.type === 'object' && schemaObj.additionalProperties) {
+        if (schemaObj.additionalProperties === true) {
+            return 'Record<string, any>';
+        }
+        const valueType = resolveSchemaTypeFromModuleSchemas(
+            schemaObj.additionalProperties as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+            moduleSchemas,
+            visitedRefs
+        );
+        return `Record<string, ${valueType || 'any'}>`;
+    }
+
+    if (schemaObj.type === 'object' && schemaObj.properties && Object.keys(schemaObj.properties).length > 0) {
+        const requiredSet = new Set(schemaObj.required || []);
+        const inlineFields = Object.entries(schemaObj.properties).map(([key, value]) => {
+            const fieldType = resolveSchemaTypeFromModuleSchemas(
+                value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+                moduleSchemas,
+                visitedRefs
+            );
+            const optional = requiredSet.has(key) ? '' : '?';
+            return `${key}${optional}: ${fieldType || 'any'}`;
+        });
+        return `{ ${inlineFields.join('; ')} }`;
+    }
+
+    const baseType = convertOpenApiTypeToTypeScript(schemaObj.type);
+    if (!baseType) return 'any';
+    return schemaObj.nullable ? `${baseType} | null` : baseType;
+}
+
+function collectSchemaProperties(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject },
+    visitedRefs: Set<string> = new Set()
+): { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } {
+    const collected: { properties: Record<string, OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject>; required: Set<string> } = {
+        properties: {},
+        required: new Set<string>(),
+    };
+    if (!schema) return collected;
+
+    if ((schema as OpenAPIV3.ReferenceObject).$ref) {
+        const ref = (schema as OpenAPIV3.ReferenceObject).$ref;
+        if (!visitedRefs.has(ref)) {
+            visitedRefs.add(ref);
+            const refName = getSchemaNameFromRef(ref);
+            const refSchema = moduleSchemas[refName];
+            if (refSchema) {
+                const nested = collectSchemaProperties(refSchema, moduleSchemas, visitedRefs);
+                Object.assign(collected.properties, nested.properties);
+                nested.required.forEach(field => collected.required.add(field));
+            }
+        }
+        return collected;
+    }
+
+    const schemaObj = schema as OpenAPIV3.SchemaObject;
+
+    if (schemaObj.allOf && Array.isArray(schemaObj.allOf)) {
+        schemaObj.allOf.forEach(item => {
+            const nested = collectSchemaProperties(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, moduleSchemas, visitedRefs);
+            Object.assign(collected.properties, nested.properties);
+            nested.required.forEach(field => collected.required.add(field));
+        });
+    }
+
+    if (schemaObj.properties) {
+        Object.entries(schemaObj.properties).forEach(([name, value]) => {
+            collected.properties[name] = value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+        });
+    }
+
+    (schemaObj.required || []).forEach(field => collected.required.add(field));
+    return collected;
+}
+
+function buildInterfaceDefinitionFromModuleSchemas(
+    typeName: string,
+    moduleSchemas: { [typeName: string]: OpenAPIV3.SchemaObject }
+): string | null {
+    const schema = moduleSchemas[typeName];
+    if (!schema) return null;
+
+    const { properties, required } = collectSchemaProperties(schema, moduleSchemas);
+    const entries = Object.entries(properties);
+    if (entries.length === 0) return null;
+
+    const lines = entries.map(([propName, propSchema]) => {
+        const optional = required.has(propName) ? '' : '?';
+        const propType = resolveSchemaTypeFromModuleSchemas(propSchema, moduleSchemas) || 'any';
+        const propDescription = (propSchema as OpenAPIV3.SchemaObject).description || '';
+        const comment = propDescription ? ` // ${propDescription}` : '';
+        return `  ${propName}${optional}: ${propType};${comment}`;
+    });
+
+    return `export interface ${typeName} {\n${lines.join('\n')}\n}`;
+}
+
 function improveTypeDefinitions(typesContent: string, endpoints: any[]): string {
     let improvedContent = typesContent;
     
@@ -100,13 +270,13 @@ function improveTypeDefinitions(typesContent: string, endpoints: any[]): string
                 let type = param.type;
                 
                 // 处理联合类型，确保正确的 TypeScript 语法
-                if (type && type.includes(' | ')) {
-                    if (type.includes('null')) {
-                        type = type.replace(/\s*\|\s*null/g, ' | null');
-                    }
-                } else {
-                    type = convertOpenApiTypeToTypeScript(type);
-                }
+                if (type && type.includes(' | ')) {
+                    if (type.includes('null')) {
+                        type = type.replace(/\s*\|\s*null/g, ' | null');
+                    }
+                } else {
+                    type = convertOpenApiTypeToTypeScript(type);
+                }
                 
                 const comment = param.description ? ` // ${param.description}` : '';
                 return `  ${param.name}${optional}: ${type};${comment}`;
@@ -542,7 +712,8 @@ export const handleBuild = async () => {
                         console.log(chalk.blue(`为模块 "${moduleName}" 生成基于 JSDoc 的类型定义...`));
                         
                         // 创建类型定义映射
-                        const typeDefinitions: { [typeName: string]: string } = {};
+                        const typeDefinitions: { [typeName: string]: string } = {};
+                        const nestedReferencedTypes = new Set<string>();
                         
                         // 从 endpoints 中提取类型定义
                         module.endpoints.forEach(endpoint => {
@@ -553,17 +724,23 @@ export const handleBuild = async () => {
                                     const optional = !param.required ? '?' : '';
                                     let type = param.type;
                                     
-                                    if (type && type.includes(' | ')) {
-                                        if (type.includes('null')) {
-                                            type = type.replace(/\s*\|\s*null/g, ' | null');
-                                        }
-                                    } else {
-                                        type = convertOpenApiTypeToTypeScript(type);
-                                    }
-                                    
-                                    const comment = param.description ? ` // ${param.description}` : '';
-                                    return `  ${param.name}${optional}: ${type};${comment}`;
-                                })
+                                    if (type && type.includes(' | ')) {
+                                        if (type.includes('null')) {
+                                            type = type.replace(/\s*\|\s*null/g, ' | null');
+                                        }
+                                    } else {
+                                        type = convertOpenApiTypeToTypeScript(type);
+                                    }
+
+                                    extractTypeIdentifiers(type).forEach(typeName => {
+                                        if (isValidTypeIdentifier(typeName)) {
+                                            nestedReferencedTypes.add(typeName);
+                                        }
+                                    });
+                                    
+                                    const comment = param.description ? ` // ${param.description}` : '';
+                                    return `  ${param.name}${optional}: ${type};${comment}`;
+                                })
                                 .join('\n');
 
                             // 处理 params 类型 - 使用 paramsJsdocParams
@@ -604,11 +781,26 @@ ${responseFields}
                         });
                         
                         // 为没有定义的类型添加基本定义
-                        allReferencedTypes.forEach(typeName => {
+                        const fallbackReferencedTypes = [
+                            ...new Set([
+                                ...allReferencedTypes,
+                                ...Object.keys(module.schemas || {}),
+                                ...nestedReferencedTypes,
+                            ])
+                        ];
+                        fallbackReferencedTypes.forEach(typeName => {
                             if (!isValidTypeIdentifier(typeName)) {
                                 return;
                             }
                             if (!typeDefinitions[typeName]) {
+                                const schemaBasedDefinition = buildInterfaceDefinitionFromModuleSchemas(
+                                    typeName,
+                                    module.schemas as { [typeName: string]: OpenAPIV3.SchemaObject }
+                                );
+                                if (schemaBasedDefinition) {
+                                    typeDefinitions[typeName] = schemaBasedDefinition;
+                                    return;
+                                }
                                 typeDefinitions[typeName] = `export interface ${typeName} {
   [key: string]: any;
 }`;

package/src/core/parser.ts

@@ -111,7 +111,7 @@ function getModuleName(path: string, pathPrefixes: Array<{ path: string; package
     return parts[0] || 'default';
 }
 
-function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
+function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string {
     if (!openApiType) return 'any';
     
     switch (openApiType) {
@@ -125,12 +125,88 @@ function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string
             return 'boolean';
         case 'string':
             return 'string';
-        case 'number':
-            return 'number';
-        default:
-            return 'any';
-    }
-}
+        case 'number':
+            return 'number';
+        default:
+            return openApiType;
+    }
+}
+
+function resolveSchemaToTypeScript(
+    schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+    allSchemas: { [key: string]: any }
+): string {
+    if (!schema) return 'any';
+
+    if (isReferenceObject(schema)) {
+        return getSchemaName(schema.$ref) || 'any';
+    }
+
+    if (schema.anyOf && Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+        const unionTypes = schema.anyOf
+            .map(item => resolveSchemaToTypeScript(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, allSchemas))
+            .filter(Boolean);
+        if (unionTypes.length > 0) {
+            return [...new Set(unionTypes)].join(' | ');
+        }
+    }
+
+    if (schema.oneOf && Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+        const unionTypes = schema.oneOf
+            .map(item => resolveSchemaToTypeScript(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, allSchemas))
+            .filter(Boolean);
+        if (unionTypes.length > 0) {
+            return [...new Set(unionTypes)].join(' | ');
+        }
+    }
+
+    if (schema.allOf && Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        const intersectionTypes = schema.allOf
+            .map(item => resolveSchemaToTypeScript(item as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, allSchemas))
+            .filter(Boolean);
+        if (intersectionTypes.length > 0) {
+            return [...new Set(intersectionTypes)].join(' & ');
+        }
+    }
+
+    if (schema.type === 'array') {
+        const itemType = resolveSchemaToTypeScript(
+            schema.items as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+            allSchemas
+        );
+        return `${itemType || 'any'}[]`;
+    }
+
+    if (schema.type === 'object') {
+        if (schema.properties && Object.keys(schema.properties).length > 0) {
+            const requiredSet = new Set(schema.required || []);
+            const inlineFields = Object.entries(schema.properties).map(([key, value]) => {
+                const fieldType = resolveSchemaToTypeScript(
+                    value as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+                    allSchemas
+                );
+                const optional = requiredSet.has(key) ? '' : '?';
+                return `${key}${optional}: ${fieldType || 'any'}`;
+            });
+            return `{ ${inlineFields.join('; ')} }`;
+        }
+        if (schema.additionalProperties) {
+            if (schema.additionalProperties === true) {
+                return 'Record<string, any>';
+            }
+            const valueType = resolveSchemaToTypeScript(
+                schema.additionalProperties as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+                allSchemas
+            );
+            return `Record<string, ${valueType || 'any'}>`;
+        }
+        return 'any';
+    }
+
+    const baseType = convertOpenApiTypeToTypeScript(schema.type);
+    const nullable = schema.nullable ? ' | null' : '';
+    return `${baseType}${nullable}`;
+}
 
 function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject, allSchemas: { [key: string]: any }): Required<Endpoint>['jsdocParams'] {
     const params: Required<Endpoint>['jsdocParams'] = [];
@@ -146,13 +222,15 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
 
     if (targetSchema?.properties) {
         for (const propName in targetSchema.properties) {
-            const prop = targetSchema.properties[propName] as OpenAPIV3.SchemaObject;
-            
-            let propType = 'any';
+            const prop = targetSchema.properties[propName] as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+            let propType = resolveSchemaToTypeScript(prop, allSchemas);
+            const propDescription = isReferenceObject(prop)
+                ? ((allSchemas[getSchemaName(prop.$ref)] as OpenAPIV3.SchemaObject | undefined)?.description || '')
+                : (prop?.description || '');
             
             // 处理 anyOf 数组 (FastAPI 常用的联合类型)
-            if (prop.anyOf && Array.isArray(prop.anyOf)) {
-                const types = prop.anyOf.map(item => {
+            if (false && (prop as OpenAPIV3.SchemaObject).anyOf && Array.isArray((prop as OpenAPIV3.SchemaObject).anyOf)) {
+                const types = (prop as OpenAPIV3.SchemaObject).anyOf!.map(item => {
                     if (isReferenceObject(item)) {
                         return getSchemaName(item.$ref);
                     } else {
@@ -173,8 +251,8 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
                 }
             }
             // 处理 oneOf 数组
-            else if (prop.oneOf && Array.isArray(prop.oneOf)) {
-                const types = prop.oneOf.map(item => {
+            else if (false && (prop as OpenAPIV3.SchemaObject).oneOf && Array.isArray((prop as OpenAPIV3.SchemaObject).oneOf)) {
+                const types = (prop as OpenAPIV3.SchemaObject).oneOf!.map(item => {
                     if (isReferenceObject(item)) {
                         return getSchemaName(item.$ref);
                     } else {
@@ -195,16 +273,26 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
                 }
             }
             // 处理普通类型
-            else if (prop.type) {
-                propType = convertOpenApiTypeToTypeScript(prop.type);
-            }
+            else if (false && (prop as OpenAPIV3.SchemaObject).type) {
+                const propSchema: any = prop as any;
+                if (propSchema.type === 'array' && propSchema.items) {
+                    if (isReferenceObject(propSchema.items)) {
+                        propType = `${getSchemaName(propSchema.items.$ref)}[]`;
+                    } else {
+                        const itemType = convertOpenApiTypeToTypeScript((propSchema.items as OpenAPIV3.SchemaObject).type);
+                        propType = `${itemType}[]`;
+                    }
+                } else {
+                    propType = convertOpenApiTypeToTypeScript(propSchema.type);
+                }
+            }
 
-            params.push({
-                name: propName,
-                type: propType,
-                description: prop?.description || '',
-                required: targetSchema.required?.includes(propName)
-            });
+            params.push({
+                name: propName,
+                type: propType || 'any',
+                description: propDescription,
+                required: targetSchema.required?.includes(propName)
+            });
         }
     }
     return params;