czh-api 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,10 +1,35 @@
 # 更新日志
 
-所有重要的版本更新都会记录在此文件中。
-
-## [1.0.3] - 2026-03-17
-
-### 新增
+所有重要的版本更新都会记录在此文件中。
+
+## [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
+
+### 修复
+- 修复响应最外层为数组（如 `type: array` + `items.$ref`）时类型生成异常的问题，避免出现非法接口声明（如 `export interface Xxx[]`）。
+- 修复仅在“数组响应”中被引用的实体类型可能退化为 `{ [key: string]: any }` 的问题，增强该场景下的类型补全稳定性。
+- 修复类型增强阶段对 `export interface` 的替换逻辑在存在内联对象字段时可能截断内容的问题，避免生成残留字段到接口外。
+- 修复部分 OpenAPI `$ref` 路径在类型编译阶段解析不一致导致的类型降级问题（兼容 `#/components/schemas/*` 场景）。
+
+### 改进
+- 优化数组响应类型推导策略：当响应为 `$ref` 数组时优先生成 `ItemType[]`，减少中间响应类型噪音。
+- 增强类型生成兜底逻辑的类型名合法性校验，避免对泛型/数组等复杂类型名误生成 `interface`。
+
+## [1.0.3] - 2026-03-17
+
+### 新增
 - 添加 `pathPrefixes` 配置项，支持自定义路径前缀分组和二级分包
 - 支持配置多个路径前缀，每个前缀可指定自定义包名或自动驼峰命名
 - 自动按路径前缀后的第一级路径进行二级分包

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,68 +48,236 @@ function convertOpenApiTypeToTypeScript(openApiType) {
         case 'number':
             return 'number';
         default:
-            return 'any';
+            return openApiType;
     }
 }
 // 改进类型定义的辅助函数
+function isValidTypeIdentifier(typeName) {
+    if (!typeName)
+        return false;
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(typeName);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function resolveInterfaceTargetType(typeName) {
+    if (typeof typeName !== 'string' || typeName.length === 0)
+        return null;
+    if (isValidTypeIdentifier(typeName))
+        return typeName;
+    const arrayMatch = typeName.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\[\]$/);
+    if (arrayMatch) {
+        return arrayMatch[1];
+    }
+    return null;
+}
+function findInterfaceBlockRange(content, typeName) {
+    const startRegex = new RegExp(`export interface ${escapeRegex(typeName)}\\s*\\{`);
+    const match = startRegex.exec(content);
+    if (!match)
+        return null;
+    const start = match.index;
+    const openBraceIndex = start + match[0].lastIndexOf('{');
+    let depth = 0;
+    for (let i = openBraceIndex; i < content.length; i++) {
+        const ch = content[i];
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return { start, end: i + 1 };
+            }
+        }
+    }
+    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;
     // 收集所有需要改进的类型定义
     const typeImprovements = {};
-    endpoints.forEach(endpoint => {
-        // 改进 params 类型
-        if (endpoint.requestParamsTypeName && endpoint.jsdocParams) {
-            const paramsFields = endpoint.jsdocParams
-                .filter((param) => param.name && param.type)
-                .map((param) => {
-                const optional = !param.required ? '?' : '';
-                let type = param.type;
-                // 处理联合类型，确保正确的 TypeScript 语法
-                if (type && type.includes(' | ')) {
-                    // 如果包含 null，确保格式正确
-                    if (type.includes('null')) {
-                        type = type.replace(/\s*\|\s*null/g, ' | null');
-                    }
-                }
-                else {
-                    // 处理基本类型转换
-                    type = convertOpenApiTypeToTypeScript(type);
+    // 辅助函数：将 jsdoc params 转换为接口字段
+    function buildFieldsFromJsdocParams(jsdocParams) {
+        return jsdocParams
+            .filter((param) => param.name && param.type)
+            .map((param) => {
+            const optional = !param.required ? '?' : '';
+            let type = param.type;
+            // 处理联合类型，确保正确的 TypeScript 语法
+            if (type && type.includes(' | ')) {
+                if (type.includes('null')) {
+                    type = type.replace(/\s*\|\s*null/g, ' | null');
                 }
-                const comment = param.description ? ` // ${param.description}` : '';
-                return `  ${param.name}${optional}: ${type};${comment}`;
-            })
-                .join('\n');
+            }
+            else {
+                type = convertOpenApiTypeToTypeScript(type);
+            }
+            const comment = param.description ? ` // ${param.description}` : '';
+            return `  ${param.name}${optional}: ${type};${comment}`;
+        })
+            .join('\n');
+    }
+    endpoints.forEach(endpoint => {
+        // 改进 params 类型 - 使用 paramsJsdocParams（仅包含 path/query 参数）
+        const requestParamsTypeName = endpoint.requestParamsTypeName;
+        if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+            const paramsFields = buildFieldsFromJsdocParams(endpoint.paramsJsdocParams);
             if (paramsFields) {
-                typeImprovements[endpoint.requestParamsTypeName] = `export interface ${endpoint.requestParamsTypeName} {
-${paramsFields}
+                typeImprovements[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
 }`;
             }
         }
-        // 改进 requestBody 类型
-        if (endpoint.requestBodyTypeName && endpoint.jsdocParams) {
-            const dataFields = endpoint.jsdocParams
-                .filter((param) => param.name && param.type)
-                .map((param) => {
-                const optional = !param.required ? '?' : '';
-                let type = param.type;
-                // 处理联合类型，确保正确的 TypeScript 语法
-                if (type && type.includes(' | ')) {
-                    // 如果包含 null，确保格式正确
-                    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}`;
-            })
-                .join('\n');
+        // 改进 requestBody 类型 - 使用 dataJsdocParams（仅包含 requestBody 参数）
+        const requestBodyTypeName = endpoint.requestBodyTypeName;
+        if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+            const dataFields = buildFieldsFromJsdocParams(endpoint.dataJsdocParams);
             if (dataFields) {
-                typeImprovements[endpoint.requestBodyTypeName] = `export interface ${endpoint.requestBodyTypeName} {
-${dataFields}
+                typeImprovements[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+            }
+        }
+        // 改进 response 类型 - 使用 responseJsdocParams（包含响应字段信息）
+        const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+        if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+            const responseFields = buildFieldsFromJsdocParams(endpoint.responseJsdocParams);
+            if (responseFields) {
+                typeImprovements[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
 }`;
             }
         }
@@ -117,9 +285,12 @@ ${dataFields}
     // 替换现有的类型定义
     Object.entries(typeImprovements).forEach(([typeName, newDefinition]) => {
         // 查找并替换现有的接口定义
-        const interfaceRegex = new RegExp(`export interface ${typeName}\\s*\\{[^}]*\\}`, 'g');
-        if (interfaceRegex.test(improvedContent)) {
-            improvedContent = improvedContent.replace(interfaceRegex, newDefinition);
+        const blockRange = findInterfaceBlockRange(improvedContent, typeName);
+        if (blockRange) {
+            improvedContent =
+                improvedContent.slice(0, blockRange.start) +
+                    newDefinition +
+                    improvedContent.slice(blockRange.end);
         }
         else {
             // 如果没找到接口定义，添加到末尾
@@ -186,6 +357,33 @@ function removeUselessTypeAliases(typesContent) {
     cleanedContent = cleanedContent.replace(/\/\*\*\n \* [^\n]*\n \*\/\n(?!export)/g, '');
     return cleanedContent;
 }
+function normalizeRef(refValue) {
+    const match = refValue.match(/^#\/components\/schemas\/([^/]+)$/);
+    if (match) {
+        return `#/definitions/${match[1]}`;
+    }
+    return refValue;
+}
+function normalizeSchemaRefs(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => normalizeSchemaRefs(item));
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        const normalized = {};
+        for (const key in obj) {
+            const currentValue = obj[key];
+            if (key === '$ref' && typeof currentValue === 'string') {
+                normalized[key] = normalizeRef(currentValue);
+            }
+            else {
+                normalized[key] = normalizeSchemaRefs(currentValue);
+            }
+        }
+        return normalized;
+    }
+    return value;
+}
 const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
     try {
         console.log(chalk_1.default.blue('Building API from source...'));
@@ -285,9 +483,10 @@ const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
             if (Object.keys(module.schemas).length > 0) {
                 console.log(chalk_1.default.blue(`正在为模块 "${moduleName}" 生成类型文件，包含 ${Object.keys(module.schemas).length} 个 schema`));
                 try {
+                    const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
                     const schemasWithTitles = {};
-                    for (const schemaName in module.schemas) {
-                        schemasWithTitles[schemaName] = Object.assign(Object.assign({}, module.schemas[schemaName]), { title: schemaName });
+                    for (const schemaName in normalizedModuleSchemas) {
+                        schemasWithTitles[schemaName] = Object.assign(Object.assign({}, normalizedModuleSchemas[schemaName]), { title: schemaName });
                     }
                     const rootSchemaForCompiler = {
                         title: 'schemas',
@@ -334,7 +533,8 @@ const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
                         // 尝试逐个验证 schema，过滤掉有问题的
                         const validSchemas = {};
                         const invalidSchemas = [];
-                        for (const schemaName in module.schemas) {
+                        const normalizedModuleSchemas = normalizeSchemaRefs(module.schemas);
+                        for (const schemaName in normalizedModuleSchemas) {
                             try {
                                 // 尝试单独编译每个 schema
                                 const testSchema = {
@@ -342,11 +542,11 @@ const handleBuild = () => __awaiter(void 0, void 0, void 0, function* () {
                                     type: 'object',
                                     properties: {},
                                     additionalProperties: false,
-                                    definitions: { [schemaName]: module.schemas[schemaName] },
-                                    components: { schemas: { [schemaName]: module.schemas[schemaName] } }
+                                    definitions: { [schemaName]: normalizedModuleSchemas[schemaName] },
+                                    components: { schemas: { [schemaName]: normalizedModuleSchemas[schemaName] } }
                                 };
                                 yield (0, json_schema_to_typescript_1.compile)(testSchema, 'test', { unreachableDefinitions: true });
-                                validSchemas[schemaName] = Object.assign(Object.assign({}, module.schemas[schemaName]), { title: schemaName });
+                                validSchemas[schemaName] = Object.assign(Object.assign({}, normalizedModuleSchemas[schemaName]), { title: schemaName });
                             }
                             catch (schemaError) {
                                 invalidSchemas.push(schemaName);
@@ -413,70 +613,83 @@ 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 => {
-                            // 处理 params 类型
-                            if (endpoint.requestParamsTypeName && endpoint.jsdocParams) {
-                                const paramsFields = endpoint.jsdocParams
-                                    .filter(param => param.name && param.type)
-                                    .map(param => {
-                                    const optional = !param.required ? '?' : '';
-                                    let type = param.type;
-                                    // 处理联合类型
-                                    if (type && type.includes(' | ')) {
-                                        // 如果包含 null，确保格式正确
-                                        if (type.includes('null')) {
-                                            type = type.replace(/\s*\|\s*null/g, ' | null');
-                                        }
+                            // 辅助函数：将 jsdoc params 转换为字段
+                            const buildFields = (params) => params
+                                .filter((param) => param.name && param.type)
+                                .map((param) => {
+                                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);
+                                }
+                                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');
+                                });
+                                const comment = param.description ? ` // ${param.description}` : '';
+                                return `  ${param.name}${optional}: ${type};${comment}`;
+                            })
+                                .join('\n');
+                            // 处理 params 类型 - 使用 paramsJsdocParams
+                            const requestParamsTypeName = endpoint.requestParamsTypeName;
+                            if (requestParamsTypeName && isValidTypeIdentifier(requestParamsTypeName) && endpoint.paramsJsdocParams && endpoint.paramsJsdocParams.length > 0) {
+                                const paramsFields = buildFields(endpoint.paramsJsdocParams);
                                 if (paramsFields) {
-                                    typeDefinitions[endpoint.requestParamsTypeName] = `export interface ${endpoint.requestParamsTypeName} {
-${paramsFields}
+                                    typeDefinitions[requestParamsTypeName] = `export interface ${requestParamsTypeName} {
+${paramsFields}
 }`;
                                 }
                             }
-                            // 处理 data 类型 (requestBody)
-                            if (endpoint.requestBodyTypeName && endpoint.jsdocParams) {
-                                const dataFields = endpoint.jsdocParams
-                                    .filter(param => param.name && param.type)
-                                    .map(param => {
-                                    const optional = !param.required ? '?' : '';
-                                    let type = param.type;
-                                    // 处理联合类型
-                                    if (type && type.includes(' | ')) {
-                                        // 如果包含 null，确保格式正确
-                                        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}`;
-                                })
-                                    .join('\n');
+                            // 处理 data 类型 (requestBody) - 使用 dataJsdocParams
+                            const requestBodyTypeName = endpoint.requestBodyTypeName;
+                            if (requestBodyTypeName && isValidTypeIdentifier(requestBodyTypeName) && endpoint.dataJsdocParams && endpoint.dataJsdocParams.length > 0) {
+                                const dataFields = buildFields(endpoint.dataJsdocParams);
                                 if (dataFields) {
-                                    typeDefinitions[endpoint.requestBodyTypeName] = `export interface ${endpoint.requestBodyTypeName} {
-${dataFields}
+                                    typeDefinitions[requestBodyTypeName] = `export interface ${requestBodyTypeName} {
+${dataFields}
+}`;
+                                }
+                            }
+                            // 处理 response 类型 - 使用 responseJsdocParams
+                            const responseTargetType = resolveInterfaceTargetType(endpoint.responseTypeName);
+                            if (responseTargetType && endpoint.responseTypeName !== 'void' && endpoint.responseJsdocParams && endpoint.responseJsdocParams.length > 0) {
+                                const responseFields = buildFields(endpoint.responseJsdocParams);
+                                if (responseFields) {
+                                    typeDefinitions[responseTargetType] = `export interface ${responseTargetType} {
+${responseFields}
 }`;
                                 }
                             }
                         });
                         // 为没有定义的类型添加基本定义
-                        allReferencedTypes.forEach(typeName => {
+                        const fallbackReferencedTypes = [
+                            ...new Set([
+                                ...allReferencedTypes,
+                                ...Object.keys(module.schemas || {}),
+                                ...nestedReferencedTypes,
+                            ])
+                        ];
+                        fallbackReferencedTypes.forEach(typeName => {
+                            if (!isValidTypeIdentifier(typeName)) {
+                                return;
+                            }
                             if (!typeDefinitions[typeName]) {
-                                typeDefinitions[typeName] = `export interface ${typeName} {
-  [key: string]: any;
+                                const schemaBasedDefinition = buildInterfaceDefinitionFromModuleSchemas(typeName, module.schemas);
+                                if (schemaBasedDefinition) {
+                                    typeDefinitions[typeName] = schemaBasedDefinition;
+                                    return;
+                                }
+                                typeDefinitions[typeName] = `export interface ${typeName} {
+  [key: string]: any;
 }`;
                             }
                         });