swagger2api-v3 1.1.9 → 1.1.11

package/dist/utils/schema.js

@@ -0,0 +1,536 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidIdentifier = isValidIdentifier;
+exports.formatTsPropertyName = formatTsPropertyName;
+exports.escapeJSDocText = escapeJSDocText;
+exports.stripNullFromUnion = stripNullFromUnion;
+exports.isObjectSchema = isObjectSchema;
+exports.isGenericResponseSchema = isGenericResponseSchema;
+exports.getVisibleSchemaProperties = getVisibleSchemaProperties;
+exports.schemaNeedsUsageVariant = schemaNeedsUsageVariant;
+exports.renderObjectMembers = renderObjectMembers;
+exports.swaggerTypeToTsType = swaggerTypeToTsType;
+exports.getRefName = getRefName;
+const naming_1 = require("./naming");
+/**
+ * 判断字符串是否为合法 TypeScript 标识符
+ * @param name 属性名
+ * @returns 是否为合法标识符
+ */
+function isValidIdentifier(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+/**
+ * 格式化 TypeScript 属性名
+ * @param name 属性名
+ * @returns 可用于类型声明的属性名
+ */
+function formatTsPropertyName(name) {
+    return isValidIdentifier(name) ? name : JSON.stringify(name);
+}
+/**
+ * 转义 JSDoc 文本
+ * @param text 原始文本
+ * @returns 可安全写入单行 JSDoc 的文本
+ */
+function escapeJSDocText(text) {
+    return text.replace(/\*\//g, '*\\/').replace(/\s+/g, ' ').trim();
+}
+/**
+ * 移除联合类型中的顶层 null 类型
+ * @param typeStr 类型字符串
+ * @returns 移除 null 后的类型字符串
+ */
+function stripNullFromUnion(typeStr) {
+    if (!typeStr)
+        return 'any';
+    const normalized = Array.from(new Set(splitTopLevelUnion(typeStr).filter((part) => part && part !== 'null')));
+    return normalized.length > 0 ? normalized.join(' | ') : 'any';
+}
+/**
+ * 判断 Schema 是否应按对象处理
+ * @param schema OpenAPI Schema
+ * @returns 是否为对象 Schema
+ */
+function isObjectSchema(schema) {
+    return (schema.type === 'object' ||
+        (schema.type === undefined &&
+            (schema.properties !== undefined ||
+                schema.additionalProperties !== undefined)));
+}
+/**
+ * 判断 Schema 是否为项目约定的泛型响应容器
+ * @param schema OpenAPI Schema
+ * @returns 是否为泛型响应容器
+ */
+function isGenericResponseSchema(schema) {
+    if (!isObjectSchema(schema) || !schema.properties?.data)
+        return false;
+    const hasCommonField = ['code', 'message', 'success', 'status'].some((field) => schema.properties?.[field] !== undefined);
+    const dataSchema = schema.properties.data;
+    const hasGenericData = isObjectSchema(dataSchema) &&
+        !dataSchema.properties &&
+        dataSchema.additionalProperties === undefined;
+    return hasCommonField && hasGenericData;
+}
+/**
+ * 获取当前使用场景可见的对象属性
+ * @param schema OpenAPI Schema
+ * @param usage Schema 使用场景
+ * @returns 可见属性数组
+ */
+function getVisibleSchemaProperties(schema, usage = 'neutral') {
+    return Object.entries(schema.properties || {}).filter(([, property]) => {
+        if (usage === 'request' && property.readOnly)
+            return false;
+        if (usage === 'response' && property.writeOnly)
+            return false;
+        return true;
+    });
+}
+/**
+ * 判断 Schema 在指定场景下是否需要独立类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 是否需要独立类型
+ */
+function schemaNeedsUsageVariant(schema, schemas, usage) {
+    return detectUsageVariant(schema, schemas, usage, new Set());
+}
+/**
+ * 渲染对象类型成员
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @param overrides 属性类型覆盖
+ * @returns 对象成员代码
+ */
+function renderObjectMembers(schema, schemas = {}, usage = 'neutral', overrides = {}) {
+    const properties = getVisibleSchemaProperties(schema, usage);
+    const propertyTypes = [];
+    let hasOptionalProperty = false;
+    const members = properties.map(([key, property]) => {
+        const optional = schema.required?.includes(key) ? '' : '?';
+        let propertyType = overrides[key] || swaggerTypeToTsType(property, schemas, usage);
+        if (optional) {
+            propertyType = stripNullFromUnion(propertyType);
+            hasOptionalProperty = true;
+        }
+        propertyTypes.push(propertyType);
+        const comment = property.description
+            ? `  /** ${escapeJSDocText(property.description)} */\n`
+            : '';
+        const readonly = property.readOnly ? 'readonly ' : '';
+        return `${comment}  ${readonly}${formatTsPropertyName(key)}${optional}: ${propertyType};`;
+    });
+    const indexMember = createAdditionalPropertiesMember(schema, schemas, usage, propertyTypes, hasOptionalProperty);
+    if (indexMember)
+        members.push(indexMember);
+    return members.join('\n');
+}
+/**
+ * 将 OpenAPI Schema 转换为 TypeScript 类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 类型字符串
+ */
+function swaggerTypeToTsType(schema, schemas = {}, usage = 'neutral') {
+    if (!schema)
+        return 'any';
+    let baseType;
+    if (schema.enum) {
+        baseType = createEnumUnion(schema.enum);
+    }
+    else if (schema.allOf) {
+        baseType = createAllOfType(schema, schemas, usage);
+    }
+    else if (schema.oneOf || schema.anyOf) {
+        baseType = createComposedUnionType(schema, schemas, usage);
+    }
+    else if (schema.$ref) {
+        baseType = createReferenceType(schema.$ref, schemas, usage);
+    }
+    else if (Array.isArray(schema.type)) {
+        baseType = createTypeArrayType(schema, schemas, usage);
+    }
+    else if (schema.type === 'array') {
+        const itemType = swaggerTypeToTsType(schema.items, schemas, usage);
+        baseType = `${parenthesizeArrayItem(itemType)}[]`;
+    }
+    else if (isObjectSchema(schema)) {
+        baseType = createObjectType(schema, schemas, usage);
+    }
+    else {
+        baseType = createPrimitiveType(schema);
+    }
+    return schema.nullable === true ? addNullableType(baseType) : baseType;
+}
+/**
+ * 创建 OpenAPI 3.1 类型数组对应的联合类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 联合类型
+ */
+function createTypeArrayType(schema, schemas, usage) {
+    const schemaTypes = Array.isArray(schema.type) ? schema.type : [];
+    const types = schemaTypes.map((type) => swaggerTypeToTsType({ ...schema, type, nullable: false }, schemas, usage));
+    return createUniqueUnion(types);
+}
+/**
+ * 从 $ref 字符串中提取并解码引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+function getRefName(ref) {
+    const segment = ref.split('/').pop() || '';
+    try {
+        return decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~');
+    }
+    catch {
+        return segment.replace(/~1/g, '/').replace(/~0/g, '~');
+    }
+}
+/**
+ * 递归检测指定场景下的访问属性差异
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @param seenRefs 已访问引用
+ * @returns 是否存在差异
+ */
+function detectUsageVariant(schema, schemas, usage, seenRefs) {
+    if (schema.$ref) {
+        const refName = getRefName(schema.$ref);
+        if (!refName || seenRefs.has(refName))
+            return false;
+        const referencedSchema = schemas[refName];
+        if (!referencedSchema)
+            return false;
+        seenRefs.add(refName);
+        return detectUsageVariant(referencedSchema, schemas, usage, seenRefs);
+    }
+    for (const property of Object.values(schema.properties || {})) {
+        if (usage === 'request' && property.readOnly)
+            return true;
+        if (usage === 'response' && property.writeOnly)
+            return true;
+        if (detectUsageVariant(property, schemas, usage, new Set(seenRefs))) {
+            return true;
+        }
+    }
+    const nestedSchemas = [
+        schema.items,
+        typeof schema.additionalProperties === 'object'
+            ? schema.additionalProperties
+            : undefined,
+        ...(schema.allOf || []),
+        ...(schema.oneOf || []),
+        ...(schema.anyOf || [])
+    ].filter((item) => !!item);
+    return nestedSchemas.some((item) => detectUsageVariant(item, schemas, usage, new Set(seenRefs)));
+}
+/**
+ * 创建枚举字面量联合类型
+ * @param values 枚举值
+ * @returns 联合类型
+ */
+function createEnumUnion(values) {
+    if (values.length === 0)
+        return 'never';
+    return createUniqueUnion(values.map((value) => toLiteralType(value)));
+}
+/**
+ * 创建 allOf 类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 交叉类型或泛型响应类型
+ */
+function createAllOfType(schema, schemas, usage) {
+    const genericType = createGenericResponseType(schema, schemas, usage);
+    const types = genericType
+        ? [genericType]
+        : (schema.allOf || [])
+            .map((item) => swaggerTypeToTsType(item, schemas, usage))
+            .filter((type) => type !== 'any');
+    const ownSchema = { ...schema, allOf: undefined, nullable: false };
+    if (hasOwnTypeConstraints(ownSchema)) {
+        types.push(swaggerTypeToTsType(ownSchema, schemas, usage));
+    }
+    const uniqueTypes = Array.from(new Set(types));
+    return uniqueTypes.length > 0
+        ? uniqueTypes.map(parenthesizeIntersectionItem).join(' & ')
+        : 'any';
+}
+/**
+ * 创建项目约定的泛型响应类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 泛型响应类型，无法匹配时返回空值
+ */
+function createGenericResponseType(schema, schemas, usage) {
+    if (schema.allOf?.length !== 2)
+        return undefined;
+    const refSchema = schema.allOf.find((item) => item.$ref);
+    const objectSchema = schema.allOf.find((item) => !item.$ref);
+    if (!refSchema?.$ref || !objectSchema?.properties)
+        return undefined;
+    const propertyEntries = Object.entries(objectSchema.properties);
+    if (propertyEntries.length !== 1 || propertyEntries[0][0] !== 'data') {
+        return undefined;
+    }
+    const refName = getRefName(refSchema.$ref);
+    const referencedSchema = schemas[refName];
+    if (!referencedSchema || !isGenericResponseSchema(referencedSchema)) {
+        return undefined;
+    }
+    const containerType = createReferenceType(refSchema.$ref, schemas, usage);
+    const dataType = swaggerTypeToTsType(propertyEntries[0][1], schemas, usage);
+    return `${containerType}<${dataType}>`;
+}
+/**
+ * 判断 Schema 是否包含 allOf 之外的类型约束
+ * @param schema OpenAPI Schema
+ * @returns 是否包含类型约束
+ */
+function hasOwnTypeConstraints(schema) {
+    const hasStructuralConstraint = !!(schema.$ref ||
+        schema.enum ||
+        schema.properties ||
+        schema.additionalProperties !== undefined ||
+        schema.items ||
+        schema.oneOf ||
+        schema.anyOf);
+    return (hasStructuralConstraint ||
+        (schema.type !== undefined && schema.type !== 'object'));
+}
+/**
+ * 创建 oneOf 或 anyOf 组合类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns 联合类型及其同级约束
+ */
+function createComposedUnionType(schema, schemas, usage) {
+    const unionType = createUniqueUnion((schema.oneOf || schema.anyOf || []).map((item) => {
+        const itemType = swaggerTypeToTsType(item, schemas, usage);
+        return createDiscriminatedUnionMember(schema, item, itemType);
+    }));
+    const ownSchema = {
+        ...schema,
+        oneOf: undefined,
+        anyOf: undefined,
+        nullable: false
+    };
+    if (!hasOwnTypeConstraints(ownSchema))
+        return unionType;
+    const ownType = swaggerTypeToTsType(ownSchema, schemas, usage);
+    return `${parenthesizeIntersectionItem(unionType)} & ${ownType}`;
+}
+/**
+ * 为联合成员添加 discriminator 字面量属性
+ * @param schema 联合 Schema
+ * @param item 联合成员 Schema
+ * @param itemType 联合成员类型
+ * @returns 可判别的联合成员类型
+ */
+function createDiscriminatedUnionMember(schema, item, itemType) {
+    const discriminator = schema.discriminator;
+    if (!discriminator || !item.$ref)
+        return itemType;
+    const refName = getRefName(item.$ref);
+    const mappedEntry = Object.entries(discriminator.mapping || {}).find(([, mappedRef]) => mappedRef === item.$ref || getRefName(mappedRef) === refName);
+    const discriminatorValue = mappedEntry?.[0] || refName;
+    if (!discriminatorValue)
+        return itemType;
+    const propertyName = formatTsPropertyName(discriminator.propertyName);
+    return `${parenthesizeIntersectionItem(itemType)} & { ${propertyName}: ${JSON.stringify(discriminatorValue)} }`;
+}
+/**
+ * 创建引用类型名称
+ * @param ref OpenAPI $ref
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 类型名称
+ */
+function createReferenceType(ref, schemas, usage) {
+    const refName = getRefName(ref);
+    const baseName = (0, naming_1.sanitizeTypeName)(refName || 'any');
+    const referencedSchema = schemas[refName];
+    if (usage !== 'neutral' &&
+        referencedSchema &&
+        schemaNeedsUsageVariant(referencedSchema, schemas, usage)) {
+        return `${baseName}${usage === 'request' ? 'Input' : 'Output'}`;
+    }
+    return baseName;
+}
+/**
+ * 创建对象类型
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @returns TypeScript 对象类型
+ */
+function createObjectType(schema, schemas, usage) {
+    const properties = getVisibleSchemaProperties(schema, usage);
+    if (properties.length === 0) {
+        if (schema.additionalProperties &&
+            typeof schema.additionalProperties === 'object') {
+            return `Record<string, ${swaggerTypeToTsType(schema.additionalProperties, schemas, usage)}>`;
+        }
+        if (schema.additionalProperties === false) {
+            return 'Record<string, never>';
+        }
+        return 'Record<string, any>';
+    }
+    return `{\n${renderObjectMembers(schema, schemas, usage)}\n}`;
+}
+/**
+ * 创建 additionalProperties 索引签名
+ * @param schema OpenAPI Schema
+ * @param schemas 全部组件 Schema
+ * @param usage Schema 使用场景
+ * @param propertyTypes 已知属性类型
+ * @param hasOptionalProperty 是否存在可选属性
+ * @returns 索引签名
+ */
+function createAdditionalPropertiesMember(schema, schemas, usage, propertyTypes, hasOptionalProperty) {
+    if (schema.additionalProperties === undefined ||
+        schema.additionalProperties === false) {
+        return undefined;
+    }
+    const additionalType = schema.additionalProperties === true
+        ? 'any'
+        : swaggerTypeToTsType(schema.additionalProperties, schemas, usage);
+    if (additionalType === 'any')
+        return '  [key: string]: any;';
+    const indexTypes = [additionalType, ...propertyTypes];
+    if (hasOptionalProperty)
+        indexTypes.push('undefined');
+    return `  [key: string]: ${createUniqueUnion(indexTypes)};`;
+}
+/**
+ * 创建基础类型
+ * @param schema OpenAPI Schema
+ * @returns TypeScript 基础类型
+ */
+function createPrimitiveType(schema) {
+    switch (schema.type) {
+        case 'integer':
+        case 'number':
+            return 'number';
+        case 'string':
+            return schema.format === 'binary' ? 'Blob' : 'string';
+        case 'boolean':
+            return 'boolean';
+        case 'null':
+            return 'null';
+        default:
+            return 'any';
+    }
+}
+/**
+ * 将枚举值转换为 TypeScript 字面量类型
+ * @param value 枚举值
+ * @returns 字面量类型字符串
+ */
+function toLiteralType(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    return 'any';
+}
+/**
+ * 创建去重后的联合类型
+ * @param types 类型数组
+ * @returns 联合类型
+ */
+function createUniqueUnion(types) {
+    if (types.includes('any'))
+        return 'any';
+    const uniqueTypes = Array.from(new Set(types.filter(Boolean)));
+    return uniqueTypes.length > 0 ? uniqueTypes.join(' | ') : 'any';
+}
+/**
+ * 为类型添加 null 联合成员
+ * @param type TypeScript 类型
+ * @returns 可空类型
+ */
+function addNullableType(type) {
+    if (type === 'any')
+        return 'any';
+    if (splitTopLevelUnion(type).includes('null'))
+        return type;
+    return `${type} | null`;
+}
+/**
+ * 拆分顶层联合类型
+ * @param typeStr 类型字符串
+ * @returns 联合类型成员
+ */
+function splitTopLevelUnion(typeStr) {
+    const parts = [];
+    let current = '';
+    let parenDepth = 0;
+    let angleDepth = 0;
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    for (const char of typeStr) {
+        if (char === '(')
+            parenDepth++;
+        else if (char === ')')
+            parenDepth = Math.max(0, parenDepth - 1);
+        else if (char === '<')
+            angleDepth++;
+        else if (char === '>')
+            angleDepth = Math.max(0, angleDepth - 1);
+        else if (char === '{')
+            braceDepth++;
+        else if (char === '}')
+            braceDepth = Math.max(0, braceDepth - 1);
+        else if (char === '[')
+            bracketDepth++;
+        else if (char === ']')
+            bracketDepth = Math.max(0, bracketDepth - 1);
+        if (char === '|' &&
+            parenDepth === 0 &&
+            angleDepth === 0 &&
+            braceDepth === 0 &&
+            bracketDepth === 0) {
+            parts.push(current.trim());
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+/**
+ * 必要时为数组元素类型添加括号
+ * @param type TypeScript 类型
+ * @returns 数组元素类型
+ */
+function parenthesizeArrayItem(type) {
+    return splitTopLevelUnion(type).length > 1 || type.includes(' & ')
+        ? `(${type})`
+        : type;
+}
+/**
+ * 必要时为交叉类型成员添加括号
+ * @param type TypeScript 类型
+ * @returns 交叉类型成员
+ */
+function parenthesizeIntersectionItem(type) {
+    return splitTopLevelUnion(type).length > 1 ? `(${type})` : type;
+}

package/dist/utils/type.d.ts

@@ -1,40 +1,22 @@
-import { SwaggerParameter, SwaggerSchema, SwaggerResponses } from '../types';
+import { SwaggerParameter, SwaggerResponses, SwaggerSchema } from '../types';
+export * from './schema';
 /**
- * 移除联合类型中的顶层 null 类型
- * @param typeStr 类型字符串
- * @returns 移除 null 后的类型字符串
- */
-export declare function stripNullFromUnion(typeStr: string): string;
-/**
- * 将 OpenAPI schema 转换为 TypeScript 类型
- * @param schema OpenAPI schema
- * @param schemas 可选的 schemas 上下文，用于查找被引用的类型定义
- * @returns TypeScript类型字符串
- */
-export declare function swaggerTypeToTsType(schema: SwaggerSchema | undefined | null, schemas?: Record<string, SwaggerSchema>): string;
-/**
- * 从 $ref 字符串中提取引用名称
- * @param ref OpenAPI $ref 字符串
- * @returns 引用名称
- */
-export declare function getRefName(ref: string): string;
-/**
- * 将 OpenAPI 参数转换为 schema 对象
+ * 将 OpenAPI 参数转换为 Schema 对象
  * @param parameter OpenAPI 参数
- * @returns 参数对应的 schema
+ * @returns 参数对应的 Schema
  */
 export declare function swaggerParameterToSchema(parameter: SwaggerParameter): SwaggerSchema;
 /**
  * 获取响应类型
  * @param responses OpenAPI 响应对象
  * @param schemas OpenAPI components.schemas
- * @returns TypeScript类型字符串
+ * @returns TypeScript 类型字符串
  */
 export declare function getResponseType(responses: SwaggerResponses, schemas?: Record<string, SwaggerSchema>): string;
 /**
- * 从 OpenAPI content 对象中获取最合适的 schema
+ * 从 OpenAPI content 对象中获取最合适的 Schema
  * @param content OpenAPI content 对象
- * @returns 匹配到的 schema
+ * @returns 匹配到的 Schema
  */
 export declare function getSchemaFromContent(content: Record<string, {
     schema?: SwaggerSchema;