czh-api 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -1,44 +1,54 @@
 # 更新日志
 
-所有重要的版本更新都会记录在此文件中。
-
-## [1.0.6] - 2026-04-14
-
-### 修复
-- 修复部分模块在 schema 编译阶段因嵌套字段 `title` 含中文标点、空值或数字开头而生成非法类型别名的问题（如 `export type = ...`、`export type 12 = ...`）。
-- 修复 `expert/groups`、`expert/customers` 等模块在同步解析时出现 `Declaration or statement expected` / `'{` expected` 报错的问题。
-
-### 改进
-- 在类型编译前新增 schema 预处理：递归移除嵌套 schema 的 `title`，仅保留顶层 schema 名称作为类型名来源，避免无效标识符影响 `json-schema-to-typescript` 生成结果。
-
-## [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
-
-### 新增
+所有重要的版本更新都会记录在此文件中。
+
+## [1.0.7] - 2026-05-19
+
+### 修复
+- 修复解析 Swagger 2.0 文档（如 Petstore）时报 `Cannot read properties of undefined (reading 'anyOf')` 的崩溃问题。
+- 修复 Swagger 2.0 中 query/path 参数缺少 `schema` 属性时，属性值被存为 `undefined` 导致后续遍历异常的问题。
+
+### 改进
+- 兼容 Swagger 2.0 参数格式：当参数无 `schema` 字段时，自动从参数对象的 `type`/`format` 构造 schema，保留类型信息。
+- 在 `extractJsdocParamsFromSchema` 中增加属性空值保护，避免异常 schema 结构导致整个构建流程中断。
+
+## [1.0.6] - 2026-04-14
+
+### 修复
+- 修复部分模块在 schema 编译阶段因嵌套字段 `title` 含中文标点、空值或数字开头而生成非法类型别名的问题（如 `export type = ...`、`export type 12 = ...`）。
+- 修复 `expert/groups`、`expert/customers` 等模块在同步解析时出现 `Declaration or statement expected` / `'{` expected` 报错的问题。
+
+### 改进
+- 在类型编译前新增 schema 预处理：递归移除嵌套 schema 的 `title`，仅保留顶层 schema 名称作为类型名来源，避免无效标识符影响 `json-schema-to-typescript` 生成结果。
+
+## [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/dist/core/parser.js

@@ -148,7 +148,7 @@ function resolveSchemaToTypeScript(schema, allSchemas) {
     return `${baseType}${nullable}`;
 }
 function extractJsdocParamsFromSchema(schema, allSchemas) {
-    var _a, _b;
+    var _a, _b, _c;
     const params = [];
     if (!schema)
         return params;
@@ -163,9 +163,13 @@ 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];
+            if (!prop) {
+                params.push({ name: propName, type: 'any', description: '', required: (_a = targetSchema.required) === null || _a === void 0 ? void 0 : _a.includes(propName) });
+                continue;
+            }
             let propType = resolveSchemaToTypeScript(prop, allSchemas);
             const propDescription = isReferenceObject(prop)
-                ? (((_a = allSchemas[getSchemaName(prop.$ref)]) === null || _a === void 0 ? void 0 : _a.description) || '')
+                ? (((_b = allSchemas[getSchemaName(prop.$ref)]) === null || _b === void 0 ? void 0 : _b.description) || '')
                 : ((prop === null || prop === void 0 ? void 0 : prop.description) || '');
             // 处理 anyOf 数组 (FastAPI 常用的联合类型)
             if (false && prop.anyOf && Array.isArray(prop.anyOf)) {
@@ -231,7 +235,7 @@ function extractJsdocParamsFromSchema(schema, allSchemas) {
                 name: propName,
                 type: propType || 'any',
                 description: propDescription,
-                required: (_b = targetSchema.required) === null || _b === void 0 ? void 0 : _b.includes(propName)
+                required: (_c = targetSchema.required) === null || _c === void 0 ? void 0 : _c.includes(propName)
             });
         }
     }
@@ -381,7 +385,8 @@ const processApi = (api, excludePaths = [], includePaths = [], pathPrefixes = []
                             // Collect params for the FormData body type
                             if (!formDataSchema.properties)
                                 formDataSchema.properties = {};
-                            formDataSchema.properties[param.name] = param.schema;
+                            const paramSchema = (param.schema || { type: param.type || 'string', format: param.format, description: param.description });
+                            formDataSchema.properties[param.name] = paramSchema;
                             if (param.required) {
                                 if (!formDataSchema.required)
                                     formDataSchema.required = [];
@@ -392,7 +397,8 @@ const processApi = (api, excludePaths = [], includePaths = [], pathPrefixes = []
                             // Always collect path params
                             if (!paramsSchema.properties)
                                 paramsSchema.properties = {};
-                            paramsSchema.properties[param.name] = param.schema;
+                            const paramSchema = (param.schema || { type: param.type || 'string', format: param.format, description: param.description });
+                            paramsSchema.properties[param.name] = paramSchema;
                             if (param.required) {
                                 if (!paramsSchema.required)
                                     paramsSchema.required = [];

package/package.json

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

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,88 +125,88 @@ function convertOpenApiTypeToTypeScript(openApiType: string | undefined): string
             return 'boolean';
         case 'string':
             return 'string';
-        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}`;
-}
+        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'] = [];
@@ -222,15 +222,19 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
 
     if (targetSchema?.properties) {
         for (const propName in targetSchema.properties) {
-            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 || '');
+            const prop = targetSchema.properties[propName] as OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject;
+            if (!prop) {
+                params.push({ name: propName, type: 'any', description: '', required: targetSchema.required?.includes(propName) });
+                continue;
+            }
+            let propType = resolveSchemaToTypeScript(prop, allSchemas);
+            const propDescription = isReferenceObject(prop)
+                ? ((allSchemas[getSchemaName(prop.$ref)] as OpenAPIV3.SchemaObject | undefined)?.description || '')
+                : (prop?.description || '');
             
             // 处理 anyOf 数组 (FastAPI 常用的联合类型)
-            if (false && (prop as OpenAPIV3.SchemaObject).anyOf && Array.isArray((prop as OpenAPIV3.SchemaObject).anyOf)) {
-                const types = (prop as OpenAPIV3.SchemaObject).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 {
@@ -251,8 +255,8 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
                 }
             }
             // 处理 oneOf 数组
-            else if (false && (prop as OpenAPIV3.SchemaObject).oneOf && Array.isArray((prop as OpenAPIV3.SchemaObject).oneOf)) {
-                const types = (prop as OpenAPIV3.SchemaObject).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 {
@@ -273,26 +277,26 @@ function extractJsdocParamsFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3
                 }
             }
             // 处理普通类型
-            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 || 'any',
-                description: propDescription,
-                required: targetSchema.required?.includes(propName)
-            });
+            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 || 'any',
+                description: propDescription,
+                required: targetSchema.required?.includes(propName)
+            });
         }
     }
     return params;
@@ -452,7 +456,8 @@ export const processApi = (api: OpenAPI.Document, excludePaths: string[] = [], i
                         } else if (isFormData && (param.in === 'query' || param.in === 'formData')) {
                             // Collect params for the FormData body type
                              if(!formDataSchema.properties) formDataSchema.properties = {};
-                             formDataSchema.properties[param.name] = param.schema as OpenAPIV3.SchemaObject;
+                             const paramSchema = (param.schema || { type: (param as any).type || 'string', format: (param as any).format, description: param.description }) as OpenAPIV3.SchemaObject;
+                             formDataSchema.properties[param.name] = paramSchema;
                              if(param.required) {
                                  if(!formDataSchema.required) formDataSchema.required = [];
                                  formDataSchema.required.push(param.name);
@@ -460,7 +465,8 @@ export const processApi = (api: OpenAPI.Document, excludePaths: string[] = [], i
                         } else if (param.in === 'path' || param.in === 'query') {
                             // Always collect path params
                             if(!paramsSchema.properties) paramsSchema.properties = {};
-                            paramsSchema.properties[param.name] = param.schema as OpenAPIV3.SchemaObject;
+                            const paramSchema = (param.schema || { type: (param as any).type || 'string', format: (param as any).format, description: param.description }) as OpenAPIV3.SchemaObject;
+                            paramsSchema.properties[param.name] = paramSchema;
                             if(param.required) {
                                 if(!paramsSchema.required) paramsSchema.required = [];
                                 paramsSchema.required.push(param.name);
@@ -558,31 +564,31 @@ export const processApi = (api: OpenAPI.Document, excludePaths: string[] = [], i
                     responseJsdocParams.push(...extractJsdocParamsFromSchema(schema, allSchemas));
                 } else if (schema && !isReferenceObject(schema)) {
                     const inlineSchema = schema as OpenAPIV3.SchemaObject;
-                    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));
-                        }
-                    }
-                }
-            }
+                    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
             const urlTemplate = path.replace(/\{(\w+)\}/g, '${params.$1}');
@@ -610,4 +616,4 @@ export const processApi = (api: OpenAPI.Document, excludePaths: string[] = [], i
     }
 
     return modules;
-}; 
+};