swagger2api-v3 1.1.2 → 1.1.4

package/README.md

@@ -36,6 +36,7 @@ npx swagger2api-v3 init
 The tool automatically generates configuration files in the corresponding format based on the project environment:
 
 **CommonJS Environment** (`"type": "commonjs"` or not set):
+
 ```javascript
 const config = {
   input: 'https://petstore.swagger.io/v2/swagger.json',
@@ -55,6 +56,7 @@ module.exports = config;
 ```
 
 **ES Module Environment** (`"type": "module"`):
+
 ```javascript
 const config = {
   // ... same configuration
@@ -71,19 +73,20 @@ npx swagger2api-v3 generate
 
 ## ⚙️ Configuration Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `input` | string | - | Swagger JSON file path or URL |
-| `output` | string | `'./src/api'` | Output directory for generated code |
-| `generator` | string | `'typescript'` | Code generator type. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation |
-| `groupByTags` | boolean | `true` | Whether to group files by tags |
-| `overwrite` | boolean | `true` | Whether to overwrite existing files |
-| `prefix` | string | `''` | Common prefix for API paths |
-| `importTemplate` | string | - | Import statement template for request function |
-| `requestStyle` | 'method' \| 'generic' | `'generic'` | Request call style: `method` uses `request.get/post`, `generic` uses `request({ method })` |
-| `lint` | string | - | Code formatting command (optional) |
-| `methodNameIgnorePrefix` | string[] | `[]` | Array of prefixes to ignore when generating method names. For example, `['api', 'auth']` will transform `apiGetName` to `getName` and `authUserInfo` to `userInfo` |
-| `options.addComments` | boolean | `true` | Whether to add detailed comments |
+| Option                   | Type                  | Default        | Description                                                                                                                                                        |
+| ------------------------ | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `input`                  | string                | -              | Swagger JSON file path or URL                                                                                                                                      |
+| `output`                 | string                | `'./src/api'`  | Output directory for generated code                                                                                                                                |
+| `generator`              | string                | `'typescript'` | Code generator type. Supports `'typescript'` and `'javascript'`. `'javascript'` outputs `.js` files and skips type file generation                                 |
+| `groupByTags`            | boolean               | `true`         | Whether to group files by tags                                                                                                                                     |
+| `overwrite`              | boolean               | `true`         | Whether to overwrite existing files                                                                                                                                |
+| `prefix`                 | string                | `''`           | Common prefix for API paths                                                                                                                                        |
+| `importTemplate`         | string                | -              | Import statement template for request function                                                                                                                     |
+| `requestStyle`           | 'method' \| 'generic' | `'generic'`    | Request call style: `method` uses `request.get/post`, `generic` uses `request({ method })`                                                                         |
+| `lint`                   | string                | -              | Code formatting command (optional)                                                                                                                                 |
+| `methodNameIgnorePrefix` | string[]              | `[]`           | Array of prefixes to ignore when generating method names. For example, `['api', 'auth']` will transform `apiGetName` to `getName` and `authUserInfo` to `userInfo` |
+| `addMethodSuffix`        | boolean               | `true`         | Whether to add HTTP method suffix to generated function names. `true` generates `userListPost`, `false` generates `userList`                                       |
+| `options.addComments`    | boolean               | `true`         | Whether to add detailed comments                                                                                                                                   |
 
 ## 📁 Generated File Structure
 
@@ -119,7 +122,12 @@ Example generated API function (generic style):
 
 ```javascript
 export const codeAuth = (data, config) => {
-  return request({ url: '/api/auth/codeAuth', method: 'POST', data, ...config });
+  return request({
+    url: '/api/auth/codeAuth',
+    method: 'POST',
+    data,
+    ...config
+  });
 };
 ```
 
@@ -222,14 +230,14 @@ Support automatic execution of formatting commands after generation:
 // In configuration file
 const config = {
   // ... other configurations
-  lint: 'prettier --write'  // or 'eslint --fix', etc.
+  lint: 'prettier --write' // or 'eslint --fix', etc.
 };
 ```
 
 ## 🤝 Contributing
 
-Issues and Pull Requests are welcome!
+If you encounter any problems or have suggestions, please feel free to [submit an issue](https://github.com/xiaoyang33/swagger2api-v3/issues) on GitHub. Pull Requests are also welcome!
 
 ## 📄 License
 
-MIT License
+MIT License

package/dist/cli/index.js

@@ -147,6 +147,11 @@ const config = {
   // 如果方法名是 apiAuthGetName，会依次移除所有匹配的前缀，最终变成 getName
   methodNameIgnorePrefix: [],
   
+  // 是否在生成的方法名中添加 HTTP method 后缀，默认为 true
+  // true: userListPost, userDetailGet
+  // false: userList, userDetail
+  addMethodSuffix: true,
+  
   // 生成选项
   options: {
     // 是否添加注释

package/dist/core/parser.d.ts

@@ -6,6 +6,11 @@ export declare class SwaggerParser {
     private document;
     private config;
     constructor(document: SwaggerDocument, config: SwaggerConfig);
+    /**
+     * 获取所有 schemas (包括 definitions 和 components.schemas)
+     * @returns schemas 对象
+     */
+    private getAllSchemas;
     /**
      * 解析所有API接口
      * @returns API接口信息数组

package/dist/core/parser.js

@@ -10,6 +10,16 @@ class SwaggerParser {
         this.document = document;
         this.config = config;
     }
+    /**
+     * 获取所有 schemas (包括 definitions 和 components.schemas)
+     * @returns schemas 对象
+     */
+    getAllSchemas() {
+        return {
+            ...(this.document.definitions || {}),
+            ...(this.document.components?.schemas || {})
+        };
+    }
     /**
      * 解析所有API接口
      * @returns API接口信息数组
@@ -70,11 +80,21 @@ class SwaggerParser {
         }
         // 生成函数名
         let functionName = operation.operationId || (0, utils_1.pathToFunctionName)(method, path);
-        // 如果使用了operationId，需要手动添加HTTP方法后缀
+        // 根据配置决定是否添加/保留 HTTP method 后缀
+        const shouldAddMethodSuffix = this.config.addMethodSuffix !== false; // 默认为 true
         if (operation.operationId) {
-            // 将HTTP方法转换为首字母大写的形式并添加到末尾
-            const methodSuffix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
-            functionName = functionName + methodSuffix;
+            // 如果使用了 operationId，根据配置决定是否添加 HTTP 方法后缀
+            if (shouldAddMethodSuffix) {
+                const methodSuffix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+                functionName = functionName + methodSuffix;
+            }
+        }
+        else {
+            // 如果没有 operationId，pathToFunctionName 已经包含了 method 后缀
+            // 如果配置为 false，需要移除后缀
+            if (!shouldAddMethodSuffix) {
+                functionName = (0, utils_1.removeMethodSuffix)(functionName, method);
+            }
         }
         // 应用前缀忽略规则
         functionName = (0, utils_1.stripMethodNamePrefixes)(functionName, this.config.methodNameIgnorePrefix);
@@ -129,14 +149,16 @@ class SwaggerParser {
         // 解析 Swagger 2.0 definitions
         if (this.document.definitions) {
             for (const [name, schema] of Object.entries(this.document.definitions)) {
-                const typeInfo = this.parseTypeDefinition(name, schema);
+                const sanitizedName = (0, utils_1.sanitizeTypeName)(name); // Use it
+                const typeInfo = this.parseTypeDefinition(sanitizedName, schema);
                 types.push(typeInfo);
             }
         }
         // 解析 OpenAPI 3.0 components.schemas
         if (this.document.components?.schemas) {
             for (const [name, schema] of Object.entries(this.document.components.schemas)) {
-                const typeInfo = this.parseTypeDefinition(name, schema);
+                const sanitizedName = (0, utils_1.sanitizeTypeName)(name); // Use it
+                const typeInfo = this.parseTypeDefinition(sanitizedName, schema);
                 types.push(typeInfo);
             }
         }
@@ -151,12 +173,14 @@ class SwaggerParser {
     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) ? '' : '?';
-                const type = (0, utils_1.swaggerTypeToTsType)(value);
+                const type = (0, utils_1.swaggerTypeToTsType)(value, allSchemas);
                 const comment = value.description
                     ? ` /** ${value.description} */`
                     : '';
@@ -166,9 +190,10 @@ class SwaggerParser {
             definition = `export interface ${typeName} {\n${properties}\n}`;
         }
         else if (schema.type === 'array') {
-            // 数组类型
-            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items);
-            definition = `export type ${typeName} = ${itemType}[];`;
+            // 数组类型 - 生成指向 items 类型的别名(不带 [])
+            // 在引用时会自动添加 []
+            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items, allSchemas);
+            definition = `export type ${typeName} = ${itemType};`;
         }
         else if (schema.enum) {
             // 枚举类型

package/dist/types/index.d.ts

@@ -31,6 +31,8 @@ export interface SwaggerConfig {
     lint?: string;
     /** 生成方法名时需要忽略的前缀数组，如 ['api', 'auth'] */
     methodNameIgnorePrefix?: string[];
+    /** 是否在生成的方法名中添加 HTTP method 后缀，默认为 true。true: userListPost, false: userList */
+    addMethodSuffix?: boolean;
 }
 /**
  * 标签分组配置

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { SwaggerDocument, SwaggerSchema, SwaggerParameter } from '../types';
+import { SwaggerDocument, SwaggerParameter } from '../types';
 /**
  * 工具函数集合
  */
@@ -34,12 +34,20 @@ export declare function toCamelCase(str: string): string;
  * @returns 移除前缀后的方法名
  */
 export declare function stripMethodNamePrefixes(methodName: string, prefixes?: string[]): string;
+/**
+ * 从函数名中移除 HTTP method 后缀
+ * @param functionName 函数名
+ * @param method HTTP 方法
+ * @returns 移除后缀后的函数名
+ */
+export declare function removeMethodSuffix(functionName: string, method: string): string;
 /**
  * 将Swagger类型转换为TypeScript类型
  * @param schema Swagger模式
+ * @param schemas 可选的 schemas 上下文,用于查找被引用的类型定义
  * @returns TypeScript类型字符串
  */
-export declare function swaggerTypeToTsType(schema?: SwaggerSchema): string;
+export declare function swaggerTypeToTsType(schema: any, schemas?: any): string;
 /**
  * 从Swagger参数生成TypeScript参数类型
  * @param parameters Swagger参数数组
@@ -87,3 +95,4 @@ export declare function sanitizeFilename(filename: string): string;
  * @returns TypeScript类型字符串
  */
 export declare function getResponseType(responses: any): string;
+export declare function sanitizeTypeName(name: string): string;

package/dist/utils/index.js

@@ -41,6 +41,7 @@ exports.toKebabCase = toKebabCase;
 exports.toPascalCase = toPascalCase;
 exports.toCamelCase = toCamelCase;
 exports.stripMethodNamePrefixes = stripMethodNamePrefixes;
+exports.removeMethodSuffix = removeMethodSuffix;
 exports.swaggerTypeToTsType = swaggerTypeToTsType;
 exports.generateParameterTypes = generateParameterTypes;
 exports.ensureDirectoryExists = ensureDirectoryExists;
@@ -50,6 +51,7 @@ exports.writeFile = writeFile;
 exports.generateApiComment = generateApiComment;
 exports.sanitizeFilename = sanitizeFilename;
 exports.getResponseType = getResponseType;
+exports.sanitizeTypeName = sanitizeTypeName;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const axios_1 = __importDefault(require("axios"));
@@ -150,26 +152,42 @@ function stripMethodNamePrefixes(methodName, prefixes) {
     }
     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;
+}
 /**
  * 将Swagger类型转换为TypeScript类型
  * @param schema Swagger模式
+ * @param schemas 可选的 schemas 上下文,用于查找被引用的类型定义
  * @returns TypeScript类型字符串
  */
-function swaggerTypeToTsType(schema) {
-    if (!schema) {
+function swaggerTypeToTsType(schema, schemas) {
+    if (!schema)
         return 'any';
-    }
-    let baseType;
-    // 处理 allOf 类型组合
-    if (schema.allOf && schema.allOf.length > 0) {
-        // 检查是否为泛型模式：第一个是引用类型，第二个定义了扩展属性
-        const firstSchema = schema.allOf[0];
-        if (firstSchema.$ref && schema.allOf.length > 1) {
-            const refName = firstSchema.$ref.split('/').pop();
-            const secondSchema = schema.allOf[1];
-            // 检查第二个 schema 是否定义了对象属性（可能没有 type 字段）
+    let baseType = 'any';
+    // 处理 allOf (通常用于继承或泛型)
+    if (schema.allOf) {
+        // 简单处理：如果是引用 + 对象定义，可能是泛型包装
+        const refSchema = schema.allOf.find((s) => s.$ref);
+        const secondSchema = schema.allOf.find((s) => !s.$ref);
+        if (refSchema && secondSchema) {
+            const refName = refSchema.$ref.split('/').pop();
+            const sanitizedRefName = sanitizeTypeName(refName || '');
+            // 检查是否是泛型容器 (如 ResOp)
+            // 注意：secondSchema 可能没有显式声明 type: 'object'，但如果有 properties，则视为对象
             if (secondSchema.properties) {
-                // 获取所有扩展属性的类型
+                // 尝试提取泛型参数类型
+                // 这里假设泛型参数是 properties 中的第一个属性
                 const propertyTypes = [];
                 for (const [propName, propSchema] of Object.entries(secondSchema.properties)) {
                     const propType = swaggerTypeToTsType(propSchema);
@@ -177,7 +195,7 @@ function swaggerTypeToTsType(schema) {
                 }
                 // 如果只有一个属性，直接作为泛型参数
                 if (propertyTypes.length === 1) {
-                    baseType = `${refName}<${propertyTypes[0]}>`;
+                    baseType = `${sanitizedRefName}<${propertyTypes[0]}>`;
                 }
                 // 如果有多个属性，组合成联合类型或对象类型
                 else if (propertyTypes.length > 1) {
@@ -188,14 +206,14 @@ function swaggerTypeToTsType(schema) {
                         return `${key}${optional}: ${type}`;
                     })
                         .join('; ')} }`;
-                    baseType = `${refName}<${combinedType}>`;
+                    baseType = `${sanitizedRefName}<${combinedType}>`;
                 }
                 else {
-                    baseType = refName || 'any';
+                    baseType = sanitizedRefName || 'any';
                 }
             }
             else {
-                baseType = refName || 'any';
+                baseType = sanitizedRefName || 'any';
             }
         }
         else {
@@ -206,10 +224,37 @@ function swaggerTypeToTsType(schema) {
             baseType = types.length > 0 ? types[0] : 'any';
         }
     }
+    // 处理 anyOf 或 oneOf
+    else if (schema.anyOf || schema.oneOf) {
+        const types = (schema.anyOf || schema.oneOf)
+            .map((s) => {
+            // 特殊处理 type: 'null'
+            if (s.type === 'null')
+                return 'null';
+            return swaggerTypeToTsType(s);
+        })
+            .filter((t) => t !== 'any');
+        // 去重
+        const uniqueTypes = Array.from(new Set(types));
+        if (uniqueTypes.length > 0) {
+            baseType = uniqueTypes.join(' | ');
+        }
+        else {
+            baseType = 'any';
+        }
+    }
     // 处理引用类型
     else if (schema.$ref) {
         const refName = schema.$ref.split('/').pop();
-        baseType = refName || 'any';
+        baseType = sanitizeTypeName(refName || 'any');
+        // 如果提供了 schemas 上下文,检查被引用的 schema 是否是数组类型
+        if (schemas && refName) {
+            const referencedSchema = schemas[refName];
+            if (referencedSchema && referencedSchema.type === 'array') {
+                // 被引用的 schema 是数组类型,添加 []
+                baseType = `${baseType}[]`;
+            }
+        }
     }
     // 处理数组类型
     else if (schema.type === 'array') {
@@ -253,6 +298,9 @@ function swaggerTypeToTsType(schema) {
             case 'file':
                 baseType = 'File';
                 break;
+            case 'null': // Add this
+                baseType = 'null';
+                break;
             default:
                 baseType = 'any';
                 break;
@@ -452,3 +500,12 @@ function getResponseType(responses) {
     }
     return 'any';
 }
+function sanitizeTypeName(name) {
+    if (!name)
+        return name;
+    // 1. 替换非法字符（包括点号）为下划线
+    const replaced = name.replace(/[^a-zA-Z0-9_]/g, '_');
+    // 2. 转换为 PascalCase
+    // 使用现有的 toPascalCase，它能处理下划线
+    return toPascalCase(replaced);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swagger2api-v3",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "A command-line tool for generating TypeScript API interfaces from Swagger (OAS 3.0) documentation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",