swagger2api-v3 1.1.7 → 1.1.9

package/dist/utils/naming.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pathToFunctionName = pathToFunctionName;
+exports.toKebabCase = toKebabCase;
+exports.toPascalCase = toPascalCase;
+exports.toCamelCase = toCamelCase;
+exports.stripMethodNamePrefixes = stripMethodNamePrefixes;
+exports.removeMethodSuffix = removeMethodSuffix;
+exports.sanitizeFilename = sanitizeFilename;
+exports.sanitizeTypeName = sanitizeTypeName;
+/**
+ * 将路径转换为小驼峰命名的函数名
+ * @param method HTTP方法
+ * @param path 接口路径
+ * @returns 小驼峰命名的函数名
+ */
+function pathToFunctionName(method, path) {
+    const cleanPath = path.replace(/\{([^}]+)\}/g, '$1');
+    const segments = cleanPath.split('/').filter((segment) => segment.length > 0);
+    const pathParts = segments.map((part, index) => {
+        const cleanPart = part.replace(/[^a-zA-Z0-9]/g, '');
+        if (index === 0) {
+            return cleanPart.toLowerCase();
+        }
+        return cleanPart.charAt(0).toUpperCase() + cleanPart.slice(1).toLowerCase();
+    });
+    const methodSuffix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+    const baseName = pathParts.join('');
+    return baseName + methodSuffix;
+}
+/**
+ * 将字符串转换为kebab-case
+ * @param str 输入字符串
+ * @returns kebab-case字符串
+ */
+function toKebabCase(str) {
+    return str
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+}
+/**
+ * 将字符串转换为PascalCase
+ * @param str 输入字符串
+ * @returns PascalCase字符串
+ */
+function toPascalCase(str) {
+    return str
+        .replace(/[\s-_]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ''))
+        .replace(/^(.)/, (char) => char.toUpperCase());
+}
+/**
+ * 将字符串转换为camelCase
+ * @param str 输入字符串
+ * @returns camelCase字符串
+ */
+function toCamelCase(str) {
+    const pascalCase = toPascalCase(str);
+    return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+/**
+ * 从方法名中移除指定的前缀
+ * @param methodName 方法名
+ * @param prefixes 需要移除的前缀数组
+ * @returns 移除前缀后的方法名
+ */
+function stripMethodNamePrefixes(methodName, prefixes) {
+    if (!prefixes || prefixes.length === 0) {
+        return methodName;
+    }
+    let result = methodName;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prefix of prefixes) {
+            if (!prefix)
+                continue;
+            const camelPrefix = toCamelCase(prefix);
+            const lowerMethodName = result.toLowerCase();
+            const lowerPrefix = camelPrefix.toLowerCase();
+            if (lowerMethodName.startsWith(lowerPrefix)) {
+                const remaining = result.substring(camelPrefix.length);
+                if (remaining.length > 0) {
+                    result = remaining.charAt(0).toLowerCase() + remaining.slice(1);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * 从函数名中移除 HTTP method 后缀
+ * @param functionName 函数名
+ * @param method HTTP 方法
+ * @returns 移除后缀后的函数名
+ */
+function removeMethodSuffix(functionName, method) {
+    const methodSuffix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+    if (functionName.endsWith(methodSuffix)) {
+        return functionName.slice(0, -methodSuffix.length);
+    }
+    return functionName;
+}
+/**
+ * 清理文件名，移除非法字符
+ * @param filename 文件名
+ * @returns 清理后的文件名
+ */
+function sanitizeFilename(filename) {
+    return filename.replace(/[<>:"/\\|?*]/g, '-').replace(/\s+/g, '-');
+}
+/**
+ * 清理类型名称并转换为 PascalCase
+ * @param name 类型名称
+ * @returns 清理后的类型名称
+ */
+function sanitizeTypeName(name) {
+    if (!name)
+        return name;
+    const replaced = name.replace(/[^a-zA-Z0-9_]/g, '_');
+    return toPascalCase(replaced);
+}

package/dist/utils/type.d.ts

@@ -0,0 +1,41 @@
+import { SwaggerParameter, SwaggerSchema, SwaggerResponses } from '../types';
+/**
+ * 移除联合类型中的顶层 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 对象
+ * @param parameter OpenAPI 参数
+ * @returns 参数对应的 schema
+ */
+export declare function swaggerParameterToSchema(parameter: SwaggerParameter): SwaggerSchema;
+/**
+ * 获取响应类型
+ * @param responses OpenAPI 响应对象
+ * @param schemas OpenAPI components.schemas
+ * @returns TypeScript类型字符串
+ */
+export declare function getResponseType(responses: SwaggerResponses, schemas?: Record<string, SwaggerSchema>): string;
+/**
+ * 从 OpenAPI content 对象中获取最合适的 schema
+ * @param content OpenAPI content 对象
+ * @returns 匹配到的 schema
+ */
+export declare function getSchemaFromContent(content: Record<string, {
+    schema?: SwaggerSchema;
+}> | undefined): SwaggerSchema | undefined;

package/dist/utils/type.js

@@ -0,0 +1,304 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripNullFromUnion = stripNullFromUnion;
+exports.swaggerTypeToTsType = swaggerTypeToTsType;
+exports.getRefName = getRefName;
+exports.swaggerParameterToSchema = swaggerParameterToSchema;
+exports.getResponseType = getResponseType;
+exports.getSchemaFromContent = getSchemaFromContent;
+const naming_1 = require("./naming");
+/**
+ * 移除联合类型中的顶层 null 类型
+ * @param typeStr 类型字符串
+ * @returns 移除 null 后的类型字符串
+ */
+function stripNullFromUnion(typeStr) {
+    if (!typeStr)
+        return 'any';
+    const parts = [];
+    let current = '';
+    let parenDepth = 0;
+    let angleDepth = 0;
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    for (let i = 0; i < typeStr.length; i++) {
+        const ch = typeStr[i];
+        if (ch === '(')
+            parenDepth++;
+        else if (ch === ')')
+            parenDepth = Math.max(0, parenDepth - 1);
+        else if (ch === '<')
+            angleDepth++;
+        else if (ch === '>')
+            angleDepth = Math.max(0, angleDepth - 1);
+        else if (ch === '{')
+            braceDepth++;
+        else if (ch === '}')
+            braceDepth = Math.max(0, braceDepth - 1);
+        else if (ch === '[')
+            bracketDepth++;
+        else if (ch === ']')
+            bracketDepth = Math.max(0, bracketDepth - 1);
+        const isTopLevel = parenDepth === 0 &&
+            angleDepth === 0 &&
+            braceDepth === 0 &&
+            bracketDepth === 0;
+        if (ch === '|' && isTopLevel) {
+            parts.push(current.trim());
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    const normalized = Array.from(new Set(parts.filter((part) => part && part !== 'null')));
+    return normalized.length > 0 ? normalized.join(' | ') : 'any';
+}
+/**
+ * 将 OpenAPI schema 转换为 TypeScript 类型
+ * @param schema OpenAPI schema
+ * @param schemas 可选的 schemas 上下文，用于查找被引用的类型定义
+ * @returns TypeScript类型字符串
+ */
+function swaggerTypeToTsType(schema, schemas) {
+    if (!schema)
+        return 'any';
+    let baseType = 'any';
+    if (Array.isArray(schema.type)) {
+        const types = schema.type.map((type) => swaggerTypeToTsType({ ...schema, type, nullable: false }, schemas));
+        const uniqueTypes = Array.from(new Set(types));
+        baseType = uniqueTypes.includes('any') ? 'any' : uniqueTypes.join(' | ');
+    }
+    else if (schema.enum) {
+        baseType = schema.enum
+            .map((value) => toLiteralType(value))
+            .join(' | ');
+    }
+    else if (schema.allOf) {
+        const refSchema = schema.allOf.find((item) => item.$ref);
+        const secondSchema = schema.allOf.find((item) => !item.$ref);
+        if (refSchema && secondSchema) {
+            const refName = getRefName(refSchema.$ref || '');
+            const sanitizedRefName = (0, naming_1.sanitizeTypeName)(refName || '');
+            if (secondSchema.properties) {
+                const propertyTypes = [];
+                for (const propSchema of Object.values(secondSchema.properties)) {
+                    const propType = swaggerTypeToTsType(propSchema, schemas);
+                    propertyTypes.push(propType);
+                }
+                if (propertyTypes.length === 1) {
+                    baseType = `${sanitizedRefName}<${propertyTypes[0]}>`;
+                }
+                else if (propertyTypes.length > 1) {
+                    const combinedType = `{ ${Object.entries(secondSchema.properties)
+                        .map(([key, value]) => {
+                        const optional = secondSchema.required?.includes(key) ? '' : '?';
+                        let type = swaggerTypeToTsType(value, schemas);
+                        if (optional === '?')
+                            type = stripNullFromUnion(type);
+                        return `${key}${optional}: ${type}`;
+                    })
+                        .join('; ')} }`;
+                    baseType = `${sanitizedRefName}<${combinedType}>`;
+                }
+                else {
+                    baseType = sanitizedRefName || 'any';
+                }
+            }
+            else {
+                baseType = sanitizedRefName || 'any';
+            }
+        }
+        else {
+            const types = schema.allOf
+                .map((item) => swaggerTypeToTsType(item))
+                .filter((type) => type !== 'any');
+            baseType = types.length > 0 ? types[0] : 'any';
+        }
+    }
+    else if (schema.anyOf || schema.oneOf) {
+        const types = (schema.anyOf || schema.oneOf).map((item) => {
+            if (item.type === 'null')
+                return 'null';
+            return swaggerTypeToTsType(item, schemas);
+        });
+        if (types.includes('any')) {
+            baseType = 'any';
+        }
+        else {
+            const uniqueTypes = Array.from(new Set(types));
+            baseType = uniqueTypes.length > 0 ? uniqueTypes.join(' | ') : 'any';
+        }
+    }
+    else if (schema.$ref) {
+        const refName = getRefName(schema.$ref);
+        baseType = (0, naming_1.sanitizeTypeName)(refName || 'any');
+        if (schemas && refName) {
+            const referencedSchema = schemas[refName];
+            if (referencedSchema && referencedSchema.type === 'array') {
+                baseType = `${baseType}[]`;
+            }
+        }
+    }
+    else if (schema.type === 'array') {
+        const itemSchema = schema.items;
+        const itemType = swaggerTypeToTsType(itemSchema, schemas);
+        if (itemSchema?.$ref && schemas) {
+            const refName = getRefName(itemSchema.$ref);
+            const referencedSchema = refName ? schemas[refName] : undefined;
+            baseType =
+                referencedSchema?.type === 'array' ? itemType : `${itemType}[]`;
+        }
+        else {
+            baseType = `${itemType}[]`;
+        }
+    }
+    else if (schema.type === 'object') {
+        if (schema.properties) {
+            const properties = Object.entries(schema.properties)
+                .map(([key, value]) => {
+                const optional = schema.required?.includes(key) ? '' : '?';
+                let type = swaggerTypeToTsType(value, schemas);
+                if (optional === '?')
+                    type = stripNullFromUnion(type);
+                return `  ${key}${optional}: ${type};`;
+            })
+                .join('\n');
+            baseType = `{\n${properties}\n}`;
+        }
+        else if (schema.additionalProperties &&
+            typeof schema.additionalProperties === 'object') {
+            const valueType = swaggerTypeToTsType(schema.additionalProperties, schemas);
+            baseType = `Record<string, ${valueType}>`;
+        }
+        else if (schema.additionalProperties === false) {
+            baseType = 'Record<string, never>';
+        }
+        else {
+            baseType = 'Record<string, any>';
+        }
+    }
+    else {
+        switch (schema.type) {
+            case 'integer':
+            case 'number':
+                baseType = 'number';
+                break;
+            case 'string':
+                baseType = 'string';
+                break;
+            case 'boolean':
+                baseType = 'boolean';
+                break;
+            case 'file':
+                baseType = 'File';
+                break;
+            case 'null':
+                baseType = 'null';
+                break;
+            default:
+                baseType = 'any';
+                break;
+        }
+    }
+    if (schema.nullable === true) {
+        if (baseType === 'any')
+            return 'any';
+        if (baseType.includes('null'))
+            return baseType;
+        return `${baseType} | null`;
+    }
+    return baseType;
+}
+/**
+ * 从 $ref 字符串中提取引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+function getRefName(ref) {
+    return ref.split('/').pop() || '';
+}
+/**
+ * 将枚举值转换为 TypeScript 字面量类型
+ * @param value 枚举值
+ * @returns 字面量类型字符串
+ */
+function toLiteralType(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return `'${value}'`;
+    return String(value);
+}
+/**
+ * 将 OpenAPI 参数转换为 schema 对象
+ * @param parameter OpenAPI 参数
+ * @returns 参数对应的 schema
+ */
+function swaggerParameterToSchema(parameter) {
+    if (parameter.schema) {
+        return parameter.schema;
+    }
+    return {
+        type: parameter.type || (parameter.items ? 'array' : 'string'),
+        format: parameter.format,
+        items: parameter.items,
+        enum: parameter.enum
+    };
+}
+/**
+ * 获取响应类型
+ * @param responses OpenAPI 响应对象
+ * @param schemas OpenAPI components.schemas
+ * @returns TypeScript类型字符串
+ */
+function getResponseType(responses, schemas) {
+    if (!responses) {
+        return 'any';
+    }
+    const successResponse = getSuccessResponse(responses);
+    if (!successResponse) {
+        return 'any';
+    }
+    const contentSchema = getSchemaFromContent(successResponse.content);
+    if (contentSchema) {
+        return swaggerTypeToTsType(contentSchema, schemas);
+    }
+    return successResponse.description === 'No Content' ? 'void' : 'any';
+}
+/**
+ * 从响应集合中获取优先成功响应
+ * @param responses OpenAPI响应对象
+ * @returns 成功响应对象
+ */
+function getSuccessResponse(responses) {
+    if (responses['200'])
+        return responses['200'];
+    if (responses['201'])
+        return responses['201'];
+    const successStatus = Object.keys(responses)
+        .filter((status) => /^2\d\d$/.test(status))
+        .sort()[0];
+    return successStatus ? responses[successStatus] : responses.default;
+}
+/**
+ * 从 OpenAPI content 对象中获取最合适的 schema
+ * @param content OpenAPI content 对象
+ * @returns 匹配到的 schema
+ */
+function getSchemaFromContent(content) {
+    if (!content)
+        return undefined;
+    const exactJson = content['application/json']?.schema;
+    if (exactJson)
+        return exactJson;
+    const jsonLikeMediaType = Object.keys(content).find((mediaType) => mediaType.endsWith('+json') || mediaType.includes('/json'));
+    if (jsonLikeMediaType && content[jsonLikeMediaType]?.schema) {
+        return content[jsonLikeMediaType].schema;
+    }
+    const firstMediaTypeWithSchema = Object.keys(content).find((mediaType) => content[mediaType]?.schema);
+    return firstMediaTypeWithSchema
+        ? content[firstMediaTypeWithSchema].schema
+        : undefined;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "swagger2api-v3",
-  "version": "1.1.7",
-  "description": "A command-line tool for generating TypeScript API interfaces from Swagger (OAS 3.0) documentation",
+  "version": "1.1.9",
+  "description": "A command-line tool for generating TypeScript API interfaces from OpenAPI 3.x / Swagger 3.0 documentation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -18,7 +18,8 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:ci": "jest --ci --coverage --watchAll=false",
-    "build": "tsc",
+    "build": "tsc && npm run copy:schema",
+    "copy:schema": "node build/copy-schema.js",
     "clean": "rimraf dist",
     "prebuild": "npm run clean",
     "start": "node dist/cli/index.js",
@@ -53,12 +54,12 @@
   },
   "packageManager": "pnpm@10.11.0",
   "devDependencies": {
-    "@types/jest": "^29.5.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^24.3.1",
-    "jest": "^29.5.0",
+    "jest": "^30.4.2",
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
-    "ts-jest": "^29.1.0",
+    "ts-jest": "^29.4.11",
     "typescript": "^5.9.2"
   },
   "dependencies": {