swagger2api-v3 1.1.9 → 1.1.11

package/dist/core/parser.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwaggerParser = void 0;
 const utils_1 = require("../utils");
+const type_generator_1 = require("./type-generator");
 const HTTP_METHODS = [
     'get',
     'post',
@@ -9,12 +10,19 @@ const HTTP_METHODS = [
     'delete',
     'patch',
     'head',
-    'options'
+    'options',
+    'trace'
 ];
+const MAX_REF_RESOLVE_DEPTH = 20;
 /**
- * Swagger文档解析器
+ * OpenAPI 3.0 文档解析器
  */
 class SwaggerParser {
+    /**
+     * 创建 OpenAPI 文档解析器
+     * @param document OpenAPI 文档
+     * @param config 生成配置
+     */
     constructor(document, config) {
         this.document = document;
         this.config = config;
@@ -33,7 +41,8 @@ class SwaggerParser {
     parseApis() {
         const apis = [];
         const paths = this.document.paths;
-        for (const [path, pathItem] of Object.entries(paths)) {
+        for (const [path, rawPathItem] of Object.entries(paths)) {
+            const pathItem = this.resolveReference(rawPathItem);
             for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (!operation)
@@ -54,10 +63,7 @@ class SwaggerParser {
      */
     parseOperation(method, path, operation, globalParameters) {
         // 合并全局参数和操作参数
-        const allParameters = [
-            ...(globalParameters || []),
-            ...(operation.parameters || [])
-        ].map((parameter) => this.resolveReference(parameter));
+        const allParameters = this.mergeParameters([...(globalParameters || []), ...(operation.parameters || [])].map((parameter) => this.resolveReference(parameter)));
         // 处理 OpenAPI 3.0 requestBody
         if (operation.requestBody) {
             const requestBody = this.resolveReference(operation.requestBody);
@@ -94,15 +100,16 @@ class SwaggerParser {
         // 应用前缀忽略规则
         functionName = (0, utils_1.stripMethodNamePrefixes)(functionName, this.config.methodNameIgnorePrefix);
         // 获取响应类型
-        const responseType = (0, utils_1.getResponseType)(operation.responses, this.getAllSchemas());
+        const responses = this.resolveResponses(operation.responses);
+        const responseType = (0, utils_1.getResponseType)(responses, this.getAllSchemas());
         // 获取请求体类型
         const bodyParam = allParameters.find((p) => p.in === 'body');
         const requestBodyType = bodyParam?.schema
-            ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema)
+            ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema, this.getAllSchemas(), 'request')
             : undefined;
         // 解析参数信息
         const parameters = allParameters.map((param) => {
-            const type = (0, utils_1.swaggerTypeToTsType)((0, utils_1.swaggerParameterToSchema)(param), this.getAllSchemas());
+            const type = (0, utils_1.swaggerTypeToTsType)((0, utils_1.swaggerParameterToSchema)(param), this.getAllSchemas(), 'request');
             return {
                 name: param.name,
                 type,
@@ -118,6 +125,7 @@ class SwaggerParser {
             path,
             description: operation.summary || operation.description,
             tags: operation.tags || [],
+            deprecated: operation.deprecated,
             parameters,
             responseType,
             requestBodyType
@@ -128,116 +136,74 @@ class SwaggerParser {
      * @returns 类型信息数组
      */
     parseTypes() {
-        const types = [];
         // Debug log
-        console.log('解析类型定义...');
-        console.log('Has components:', !!this.document.components);
+        utils_1.logger.debug('解析类型定义...');
+        utils_1.logger.debugKV('components', !!this.document.components);
         if (this.document.components) {
-            console.log('Has schemas:', !!this.document.components.schemas);
+            utils_1.logger.debugKV('schemas', !!this.document.components.schemas);
             if (this.document.components.schemas) {
-                console.log('Schema keys:', Object.keys(this.document.components.schemas));
-            }
-        }
-        // 解析 OpenAPI 3.x components.schemas
-        if (this.document.components?.schemas) {
-            for (const [name, schema] of Object.entries(this.document.components.schemas)) {
-                const sanitizedName = (0, utils_1.sanitizeTypeName)(name); // Use it
-                const typeInfo = this.parseTypeDefinition(sanitizedName, schema);
-                types.push(typeInfo);
+                utils_1.logger.debugKV('schema 列表', Object.keys(this.document.components.schemas).join(', '));
             }
         }
-        return types;
-    }
-    /**
-     * 解析单个类型定义
-     * @param name 类型名称
-     * @param schema 模式对象
-     * @returns 类型信息
-     */
-    parseTypeDefinition(name, schema) {
-        const typeName = (0, utils_1.toPascalCase)(name);
-        let definition;
-        // 获取所有 schemas 用于类型解析
-        const allSchemas = this.getAllSchemas();
-        if (schema.type === 'object' && schema.properties) {
-            // 对象类型
-            const properties = Object.entries(schema.properties)
-                .map(([key, value]) => {
-                const optional = schema.required?.includes(key) ? '' : '?';
-                let type = (0, utils_1.swaggerTypeToTsType)(value, allSchemas);
-                if (optional === '?')
-                    type = (0, utils_1.stripNullFromUnion)(type);
-                const comment = value.description
-                    ? ` /** ${value.description} */`
-                    : '';
-                return `${comment}\n  ${key}${optional}: ${type};`;
-            })
-                .join('\n');
-            definition = `export interface ${typeName} {\n${properties}\n}`;
-        }
-        else if (schema.type === 'array') {
-            // 数组类型 - 生成指向 items 类型的别名(不带 [])
-            // 在引用时会自动添加 []
-            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items || {}, allSchemas);
-            definition = `export type ${typeName} = ${itemType};`;
-        }
-        else if (schema.enum) {
-            // 枚举类型
-            const enumValues = schema.enum
-                .map((value, index) => {
-                const key = this.getEnumMemberName(schema, value, index);
-                return `  ${key} = '${value}'`;
-            })
-                .join(',\n');
-            definition = `export enum ${typeName} {\n${enumValues}\n}`;
-        }
-        else {
-            // 其他类型
-            const type = (0, utils_1.swaggerTypeToTsType)(schema);
-            definition = `export type ${typeName} = ${type};`;
-        }
-        return {
-            name: typeName,
-            definition,
-            description: schema.description
-        };
-    }
-    /**
-     * 获取枚举成员名称
-     * @param schema 枚举 schema
-     * @param value 枚举值
-     * @param index 枚举值索引
-     * @returns 枚举成员名称
-     */
-    getEnumMemberName(schema, value, index) {
-        const extensionName = schema['x-enum-varnames']?.[index] || schema['x-enumNames']?.[index];
-        if (extensionName) {
-            return extensionName;
-        }
-        const strValue = String(value);
-        if (/^\d+$/.test(strValue)) {
-            return `VALUE_${strValue}`;
-        }
-        return strValue.toUpperCase();
+        return new type_generator_1.OpenAPITypeGenerator(this.getAllSchemas()).generate();
     }
     /**
      * 解析本地 $ref 引用对象
      * @param value 可能带有 $ref 的对象
+     * @param seenRefs 已访问的引用
+     * @param depth 当前解析深度
      * @returns 引用解析后的对象
      */
-    resolveReference(value) {
+    resolveReference(value, seenRefs = new Set(), depth = 0) {
         if (!value || !value.$ref) {
             return value;
         }
-        const refPath = value.$ref.replace(/^#\//, '').split('/');
+        const ref = value.$ref;
+        if (!ref.startsWith('#/')) {
+            throw new Error(`外部 $ref 需要先通过 loadSwaggerDocument 打包: ${ref}`);
+        }
+        if (depth >= MAX_REF_RESOLVE_DEPTH) {
+            throw new Error(`$ref 解析超过最大深度: ${ref}`);
+        }
+        if (seenRefs.has(ref)) {
+            throw new Error(`检测到循环 $ref 引用: ${ref}`);
+        }
+        seenRefs.add(ref);
+        const refPath = ref
+            .replace(/^#\//, '')
+            .split('/')
+            .map((segment) => decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~'));
         let current = this.document;
         for (const segment of refPath) {
             current = current?.[segment];
-            if (!current) {
-                return value;
+            if (current === undefined) {
+                throw new Error(`无法解析 $ref 引用: ${ref}`);
             }
         }
-        return current;
+        return this.resolveReference(current, seenRefs, depth + 1);
+    }
+    /**
+     * 解析响应对象中的本地引用
+     * @param responses OpenAPI 响应集合
+     * @returns 已解析的响应集合
+     */
+    resolveResponses(responses) {
+        return Object.fromEntries(Object.entries(responses).map(([status, response]) => [
+            status,
+            this.resolveReference(response)
+        ]));
+    }
+    /**
+     * 合并同名同位置参数，后出现的 operation 级参数覆盖 path 级参数
+     * @param parameters 参数数组
+     * @returns 合并后的参数数组
+     */
+    mergeParameters(parameters) {
+        const merged = new Map();
+        for (const parameter of parameters) {
+            merged.set(`${parameter.in}:${parameter.name}`, parameter);
+        }
+        return Array.from(merged.values());
     }
     /**
      * 按标签分组API
@@ -248,7 +214,9 @@ class SwaggerParser {
         const groupedApis = new Map();
         for (const api of apis) {
             const tags = api.tags.length > 0 ? api.tags : ['default'];
-            for (const tag of tags) {
+            const strategy = this.config.multiTagStrategy ?? 'first';
+            const groupTags = strategy === 'all' ? [tags.join('-')] : [tags[0]];
+            for (const tag of groupTags) {
                 if (!groupedApis.has(tag)) {
                     groupedApis.set(tag, []);
                 }
@@ -268,7 +236,8 @@ class SwaggerParser {
             this.document.tags.forEach((tag) => tags.add(tag.name));
         }
         // 从路径操作中获取
-        for (const pathItem of Object.values(this.document.paths)) {
+        for (const rawPathItem of Object.values(this.document.paths)) {
+            const pathItem = this.resolveReference(rawPathItem);
             for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (operation?.tags) {

package/dist/core/query-parameter-generator.d.ts

@@ -0,0 +1,26 @@
+import { ApiInfo, TypeInfo } from '../types';
+/** API 查询参数类型及其所属接口 */
+export interface QueryParameterTypeInfo extends TypeInfo {
+    /** 所属 API */
+    api: ApiInfo;
+}
+/**
+ * 获取 API 查询参数类型名称
+ * @param api API 接口信息
+ * @returns 查询参数类型名称
+ */
+export declare function getQueryParameterTypeName(api: ApiInfo): string;
+/**
+ * 创建 API 查询参数类型
+ * @param apis API 接口数组
+ * @param reservedTypeNames 已占用的类型名称
+ * @returns 查询参数类型定义
+ */
+export declare function generateQueryParameterTypes(apis: ApiInfo[], reservedTypeNames?: Iterable<string>): QueryParameterTypeInfo[];
+/**
+ * 收集查询参数类型依赖的组件模型
+ * @param apis API 接口数组
+ * @param modelTypes 组件模型类型
+ * @returns 组件模型名称
+ */
+export declare function collectQueryParameterModelTypes(apis: ApiInfo[], modelTypes: TypeInfo[]): string[];

package/dist/core/query-parameter-generator.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getQueryParameterTypeName = getQueryParameterTypeName;
+exports.generateQueryParameterTypes = generateQueryParameterTypes;
+exports.collectQueryParameterModelTypes = collectQueryParameterModelTypes;
+const utils_1 = require("../utils");
+const PRIMITIVE_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'object',
+    'array',
+    'any',
+    'blob',
+    'void',
+    'null',
+    'undefined'
+]);
+/**
+ * 获取 API 查询参数类型名称
+ * @param api API 接口信息
+ * @returns 查询参数类型名称
+ */
+function getQueryParameterTypeName(api) {
+    return `${(0, utils_1.sanitizeTypeName)(api.name)}Params`;
+}
+/**
+ * 创建 API 查询参数类型
+ * @param apis API 接口数组
+ * @param reservedTypeNames 已占用的类型名称
+ * @returns 查询参数类型定义
+ */
+function generateQueryParameterTypes(apis, reservedTypeNames = []) {
+    const parameterTypes = [];
+    const usedTypeNames = new Set(reservedTypeNames);
+    for (const api of apis) {
+        const queryParameters = api.parameters.filter((parameter) => parameter.in === 'query');
+        if (queryParameters.length === 0)
+            continue;
+        const typeName = createAvailableTypeName(getQueryParameterTypeName(api), usedTypeNames);
+        usedTypeNames.add(typeName);
+        const members = renderQueryParameterMembers(queryParameters);
+        parameterTypes.push({
+            api,
+            name: typeName,
+            definition: `export interface ${typeName} {\n${members}\n}`
+        });
+    }
+    return parameterTypes;
+}
+/**
+ * 创建未被占用的类型名称
+ * @param baseName 基础类型名称
+ * @param usedTypeNames 已占用的类型名称
+ * @returns 可用类型名称
+ */
+function createAvailableTypeName(baseName, usedTypeNames) {
+    if (!usedTypeNames.has(baseName))
+        return baseName;
+    let suffix = 1;
+    while (usedTypeNames.has(`${baseName}${suffix}`))
+        suffix++;
+    return `${baseName}${suffix}`;
+}
+/**
+ * 收集查询参数类型依赖的组件模型
+ * @param apis API 接口数组
+ * @param modelTypes 组件模型类型
+ * @returns 组件模型名称
+ */
+function collectQueryParameterModelTypes(apis, modelTypes) {
+    const modelTypeNames = new Set(modelTypes.map((type) => type.name));
+    const usedTypeNames = new Set();
+    for (const api of apis) {
+        for (const parameter of api.parameters) {
+            if (parameter.in !== 'query')
+                continue;
+            extractTypeNames(parameter.type).forEach((name) => {
+                if (modelTypeNames.has(name))
+                    usedTypeNames.add(name);
+            });
+        }
+    }
+    return Array.from(usedTypeNames).sort();
+}
+/**
+ * 渲染查询参数类型成员
+ * @param parameters 查询参数数组
+ * @returns 查询参数类型成员
+ */
+function renderQueryParameterMembers(parameters) {
+    return parameters
+        .map((parameter) => {
+        const optional = parameter.required ? '' : '?';
+        const type = optional
+            ? (0, utils_1.stripNullFromUnion)(parameter.type)
+            : parameter.type;
+        const comment = parameter.description
+            ? `  /** ${(0, utils_1.escapeJSDocText)(parameter.description)} */\n`
+            : '';
+        const member = `${(0, utils_1.formatTsPropertyName)(parameter.name)}${optional}: ${type}`;
+        return `${comment}  ${member};`;
+    })
+        .join('\n');
+}
+/**
+ * 从类型字符串中提取非基础类型名称
+ * @param type 类型字符串
+ * @returns 类型名称
+ */
+function extractTypeNames(type) {
+    const matches = type.match(/[A-Za-z_][A-Za-z0-9_]*/g) || [];
+    return Array.from(new Set(matches.filter((name) => !PRIMITIVE_TYPES.has(name.toLowerCase()))));
+}

package/dist/core/type-generator.d.ts

@@ -0,0 +1,73 @@
+import { SwaggerSchema, TypeInfo } from '../types';
+/**
+ * OpenAPI 组件类型生成器
+ */
+export declare class OpenAPITypeGenerator {
+    private readonly schemas;
+    /**
+     * 创建类型生成器
+     * @param schemas OpenAPI components.schemas
+     */
+    constructor(schemas: Record<string, SwaggerSchema>);
+    /**
+     * 生成全部组件类型
+     * @returns 类型信息数组
+     */
+    generate(): TypeInfo[];
+    /**
+     * 创建单个类型信息
+     * @param typeName 输出类型名称
+     * @param schema OpenAPI Schema
+     * @param usage Schema 使用场景
+     * @returns 类型信息
+     */
+    private createTypeInfo;
+    /**
+     * 创建类型定义
+     * @param typeName 输出类型名称
+     * @param schema OpenAPI Schema
+     * @param usage Schema 使用场景
+     * @returns TypeScript 类型定义
+     */
+    private createDefinition;
+    /**
+     * 判断 Schema 是否可以生成 TypeScript enum
+     * @param schema OpenAPI Schema
+     * @returns 是否可以生成 enum
+     */
+    private canGenerateEnum;
+    /**
+     * 创建枚举定义
+     * @param typeName 枚举名称
+     * @param schema 枚举 Schema
+     * @returns TypeScript 枚举定义
+     */
+    private createEnumDefinition;
+    /**
+     * 创建合法且唯一的枚举成员名称
+     * @param schema 枚举 Schema
+     * @param value 枚举值
+     * @param index 枚举索引
+     * @param usedNames 已使用名称
+     * @returns 枚举成员名称
+     */
+    private createEnumMemberName;
+    /**
+     * 从枚举值创建默认成员名称
+     * @param value 枚举值
+     * @param index 枚举索引
+     * @returns 默认成员名称
+     */
+    private createEnumValueName;
+    /**
+     * 校验基础类型和请求/响应变体不会重名
+     */
+    private validateGeneratedTypeNames;
+    /**
+     * 注册生成类型名称并检测冲突
+     * @param owners 类型名称归属映射
+     * @param typeName 生成类型名称
+     * @param owner 原始 Schema 描述
+     */
+    private registerTypeName;
+}

package/dist/core/type-generator.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAPITypeGenerator = void 0;
+const schema_1 = require("../utils/schema");
+const naming_1 = require("../utils/naming");
+const RESERVED_IDENTIFIERS = new Set([
+    'break',
+    'case',
+    'catch',
+    'class',
+    'const',
+    'continue',
+    'debugger',
+    'default',
+    'delete',
+    'do',
+    'else',
+    'enum',
+    'export',
+    'extends',
+    'false',
+    'finally',
+    'for',
+    'function',
+    'if',
+    'import',
+    'in',
+    'instanceof',
+    'new',
+    'null',
+    'return',
+    'super',
+    'switch',
+    'this',
+    'throw',
+    'true',
+    'try',
+    'typeof',
+    'var',
+    'void',
+    'while',
+    'with',
+    'yield'
+]);
+/**
+ * OpenAPI 组件类型生成器
+ */
+class OpenAPITypeGenerator {
+    /**
+     * 创建类型生成器
+     * @param schemas OpenAPI components.schemas
+     */
+    constructor(schemas) {
+        this.schemas = schemas;
+    }
+    /**
+     * 生成全部组件类型
+     * @returns 类型信息数组
+     */
+    generate() {
+        this.validateGeneratedTypeNames();
+        const types = [];
+        for (const [schemaName, schema] of Object.entries(this.schemas)) {
+            const typeName = (0, naming_1.sanitizeTypeName)(schemaName);
+            types.push(this.createTypeInfo(typeName, schema, 'neutral'));
+            if ((0, schema_1.schemaNeedsUsageVariant)(schema, this.schemas, 'request')) {
+                types.push(this.createTypeInfo(`${typeName}Input`, schema, 'request'));
+            }
+            if ((0, schema_1.schemaNeedsUsageVariant)(schema, this.schemas, 'response')) {
+                types.push(this.createTypeInfo(`${typeName}Output`, schema, 'response'));
+            }
+        }
+        return types;
+    }
+    /**
+     * 创建单个类型信息
+     * @param typeName 输出类型名称
+     * @param schema OpenAPI Schema
+     * @param usage Schema 使用场景
+     * @returns 类型信息
+     */
+    createTypeInfo(typeName, schema, usage) {
+        return {
+            name: typeName,
+            definition: this.createDefinition(typeName, schema, usage),
+            description: schema.description
+                ? (0, schema_1.escapeJSDocText)(schema.description)
+                : undefined
+        };
+    }
+    /**
+     * 创建类型定义
+     * @param typeName 输出类型名称
+     * @param schema OpenAPI Schema
+     * @param usage Schema 使用场景
+     * @returns TypeScript 类型定义
+     */
+    createDefinition(typeName, schema, usage) {
+        if (schema.enum && this.canGenerateEnum(schema)) {
+            return this.createEnumDefinition(typeName, schema);
+        }
+        if ((0, schema_1.isObjectSchema)(schema) &&
+            !schema.allOf &&
+            !schema.oneOf &&
+            !schema.anyOf &&
+            !schema.$ref &&
+            schema.nullable !== true &&
+            (0, schema_1.getVisibleSchemaProperties)(schema, usage).length > 0) {
+            const isGeneric = (0, schema_1.isGenericResponseSchema)(schema);
+            const genericDeclaration = isGeneric ? '<T = Record<string, any>>' : '';
+            const members = (0, schema_1.renderObjectMembers)(schema, this.schemas, usage, isGeneric ? { data: 'T' } : {});
+            return `export interface ${typeName}${genericDeclaration} {\n${members}\n}`;
+        }
+        const type = (0, schema_1.swaggerTypeToTsType)(schema, this.schemas, usage);
+        return `export type ${typeName} = ${type};`;
+    }
+    /**
+     * 判断 Schema 是否可以生成 TypeScript enum
+     * @param schema OpenAPI Schema
+     * @returns 是否可以生成 enum
+     */
+    canGenerateEnum(schema) {
+        return (schema.nullable !== true &&
+            !!schema.enum?.length &&
+            schema.enum.every((value) => typeof value === 'string' || typeof value === 'number'));
+    }
+    /**
+     * 创建枚举定义
+     * @param typeName 枚举名称
+     * @param schema 枚举 Schema
+     * @returns TypeScript 枚举定义
+     */
+    createEnumDefinition(typeName, schema) {
+        const usedNames = new Set();
+        const members = (schema.enum || []).map((value, index) => {
+            const memberName = this.createEnumMemberName(schema, value, index, usedNames);
+            return `  ${memberName} = ${JSON.stringify(value)}`;
+        });
+        return `export enum ${typeName} {\n${members.join(',\n')}\n}`;
+    }
+    /**
+     * 创建合法且唯一的枚举成员名称
+     * @param schema 枚举 Schema
+     * @param value 枚举值
+     * @param index 枚举索引
+     * @param usedNames 已使用名称
+     * @returns 枚举成员名称
+     */
+    createEnumMemberName(schema, value, index, usedNames) {
+        const extensionName = schema['x-enum-varnames']?.[index] || schema['x-enumNames']?.[index];
+        const sourceName = extensionName || this.createEnumValueName(value, index);
+        let memberName = sourceName.replace(/[^A-Za-z0-9_$]+/g, '_');
+        if (!memberName)
+            memberName = `VALUE_${index}`;
+        if (/^\d/.test(memberName))
+            memberName = `VALUE_${memberName}`;
+        if (RESERVED_IDENTIFIERS.has(memberName))
+            memberName = `_${memberName}`;
+        if (!(0, schema_1.isValidIdentifier)(memberName))
+            memberName = `VALUE_${index}`;
+        const baseName = memberName;
+        let suffix = 2;
+        while (usedNames.has(memberName)) {
+            memberName = `${baseName}_${suffix}`;
+            suffix++;
+        }
+        usedNames.add(memberName);
+        return memberName;
+    }
+    /**
+     * 从枚举值创建默认成员名称
+     * @param value 枚举值
+     * @param index 枚举索引
+     * @returns 默认成员名称
+     */
+    createEnumValueName(value, index) {
+        if (typeof value === 'number') {
+            return `VALUE_${String(value)
+                .replace(/^-/, 'NEGATIVE_')
+                .replace(/\./g, '_')}`;
+        }
+        const text = String(value).trim();
+        return text ? text.toUpperCase() : `VALUE_${index}`;
+    }
+    /**
+     * 校验基础类型和请求/响应变体不会重名
+     */
+    validateGeneratedTypeNames() {
+        const owners = new Map();
+        for (const [schemaName, schema] of Object.entries(this.schemas)) {
+            const typeName = (0, naming_1.sanitizeTypeName)(schemaName);
+            this.registerTypeName(owners, typeName, schemaName);
+            if ((0, schema_1.schemaNeedsUsageVariant)(schema, this.schemas, 'request')) {
+                this.registerTypeName(owners, `${typeName}Input`, `${schemaName} 的请求类型`);
+            }
+            if ((0, schema_1.schemaNeedsUsageVariant)(schema, this.schemas, 'response')) {
+                this.registerTypeName(owners, `${typeName}Output`, `${schemaName} 的响应类型`);
+            }
+        }
+    }
+    /**
+     * 注册生成类型名称并检测冲突
+     * @param owners 类型名称归属映射
+     * @param typeName 生成类型名称
+     * @param owner 原始 Schema 描述
+     */
+    registerTypeName(owners, typeName, owner) {
+        const existingOwner = owners.get(typeName);
+        if (existingOwner && existingOwner !== owner) {
+            throw new Error(`Schema 类型名称冲突: ${existingOwner} 和 ${owner} 都会生成 ${typeName}`);
+        }
+        owners.set(typeName, owner);
+    }
+}
+exports.OpenAPITypeGenerator = OpenAPITypeGenerator;