swagger2api-v3 1.1.8 → 1.1.9

package/README.md

@@ -2,12 +2,12 @@
 
 English | [中文](./README_CN.md)
 
-A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.0 documentation.
+A powerful command-line tool for automatically generating TypeScript or JavaScript interface code from OpenAPI 3.x / Swagger 3.0 documentation.
 
 ## ✨ Features
 
-- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from Swagger JSON
-- 📁 **Smart Grouping** - Support automatic file grouping by Swagger tags
+- 🚀 **Fast Generation** - Quickly generate TypeScript interface code from OpenAPI/Swagger 3.0 JSON
+- 📁 **Smart Grouping** - Support automatic file grouping by document tags
 - 📝 **Detailed Comments** - Automatically generate detailed comments including descriptions, parameters, and return values
 - 🎨 **Code Formatting** - Support custom formatting commands
 - ⚙️ **Environment Adaptation** - Automatically detect project environment and generate corresponding configuration files
@@ -75,7 +75,7 @@ npx swagger2api-v3 generate
 | Option                   | Type                  | Default        | Description                                                                                                                                                        |
 | ------------------------ | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `$schema`                | string                | -              | Local JSON Schema path for editor completion. The default points to `node_modules/swagger2api-v3/dist/.swagger2api.schema.json`                                    |
-| `input`                  | string                | -              | Swagger JSON file path or URL                                                                                                                                      |
+| `input`                  | string                | -              | OpenAPI/Swagger 3.0 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                                                                                                                                     |

package/dist/core/generator.js

@@ -35,7 +35,10 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CodeGenerator = void 0;
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const util_1 = require("util");
 const utils_1 = require("../utils");
+const execPromise = (0, util_1.promisify)(child_process_1.exec);
 /**
  * 代码生成器
  */
@@ -433,16 +436,18 @@ class CodeGenerator {
             this.config.options?.generateModels !== false) {
             exports.push("export * from './types';");
         }
-        if (this.config.groupByTags) {
-            // 按标签导出
-            for (const tag of groupedApis.keys()) {
-                const folderName = this.getTagFileName(tag);
-                exports.push(`export * from './${folderName}';`);
+        if (this.config.options?.generateApis !== false) {
+            if (this.config.groupByTags) {
+                // 按标签导出
+                for (const tag of groupedApis.keys()) {
+                    const folderName = this.getTagFileName(tag);
+                    exports.push(`export * from './${folderName}';`);
+                }
+            }
+            else {
+                // 导出单个API文件
+                exports.push("export * from './api';");
             }
-        }
-        else {
-            // 导出单个API文件
-            exports.push("export * from './api';");
         }
         const content = [this.generateHeader(), '', ...exports, ''].join('\n');
         const ext = this.config.generator === 'javascript' ? 'js' : 'ts';
@@ -487,9 +492,6 @@ class CodeGenerator {
         if (!this.config.lint)
             return;
         try {
-            const { exec } = require('child_process');
-            const util = require('util');
-            const execPromise = util.promisify(exec);
             console.log(`🎨 Running lint command: ${this.config.lint} ${this.config.output}`);
             const result = await execPromise(`${this.config.lint} ${this.config.output}`);
             if (result.stdout) {

package/dist/core/parser.d.ts

@@ -37,6 +37,14 @@ export declare class SwaggerParser {
      * @returns 类型信息
      */
     private parseTypeDefinition;
+    /**
+     * 获取枚举成员名称
+     * @param schema 枚举 schema
+     * @param value 枚举值
+     * @param index 枚举值索引
+     * @returns 枚举成员名称
+     */
+    private getEnumMemberName;
     /**
      * 解析本地 $ref 引用对象
      * @param value 可能带有 $ref 的对象

package/dist/core/parser.js

@@ -2,6 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SwaggerParser = void 0;
 const utils_1 = require("../utils");
+const HTTP_METHODS = [
+    'get',
+    'post',
+    'put',
+    'delete',
+    'patch',
+    'head',
+    'options'
+];
 /**
  * Swagger文档解析器
  */
@@ -25,16 +34,7 @@ class SwaggerParser {
         const apis = [];
         const paths = this.document.paths;
         for (const [path, pathItem] of Object.entries(paths)) {
-            const methods = [
-                'get',
-                'post',
-                'put',
-                'delete',
-                'patch',
-                'head',
-                'options'
-            ];
-            for (const method of methods) {
+            for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (!operation)
                     continue;
@@ -97,7 +97,7 @@ class SwaggerParser {
         const responseType = (0, utils_1.getResponseType)(operation.responses, this.getAllSchemas());
         // 获取请求体类型
         const bodyParam = allParameters.find((p) => p.in === 'body');
-        const requestBodyType = bodyParam
+        const requestBodyType = bodyParam?.schema
             ? (0, utils_1.swaggerTypeToTsType)(bodyParam.schema)
             : undefined;
         // 解析参数信息
@@ -178,28 +178,14 @@ class SwaggerParser {
         else if (schema.type === 'array') {
             // 数组类型 - 生成指向 items 类型的别名(不带 [])
             // 在引用时会自动添加 []
-            const itemType = (0, utils_1.swaggerTypeToTsType)(schema.items, allSchemas);
+            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) => {
-                let key = value;
-                // 优先使用 x-enum-varnames 或 x-enumNames 扩展字段
-                if ((schema['x-enum-varnames'] && schema['x-enum-varnames'][index]) ||
-                    (schema['x-enumNames'] && schema['x-enumNames'][index])) {
-                    key =
-                        schema['x-enum-varnames']?.[index] ||
-                            schema['x-enumNames']?.[index];
-                }
-                else if (/^\d+$/.test(value)) {
-                    // 对于数字枚举，使用 VALUE_ 前缀
-                    key = `VALUE_${value}`;
-                }
-                else {
-                    key = value.toUpperCase();
-                }
+                const key = this.getEnumMemberName(schema, value, index);
                 return `  ${key} = '${value}'`;
             })
                 .join(',\n');
@@ -216,6 +202,24 @@ class SwaggerParser {
             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();
+    }
     /**
      * 解析本地 $ref 引用对象
      * @param value 可能带有 $ref 的对象
@@ -265,16 +269,7 @@ class SwaggerParser {
         }
         // 从路径操作中获取
         for (const pathItem of Object.values(this.document.paths)) {
-            const methods = [
-                'get',
-                'post',
-                'put',
-                'delete',
-                'patch',
-                'head',
-                'options'
-            ];
-            for (const method of methods) {
+            for (const method of HTTP_METHODS) {
                 const operation = pathItem[method];
                 if (operation?.tags) {
                     operation.tags.forEach((tag) => tags.add(tag));

package/dist/types/index.d.ts

@@ -286,6 +286,10 @@ export interface SwaggerSchema {
     externalDocs?: SwaggerExternalDocs;
     nullable?: boolean;
     deprecated?: boolean;
+    /** OpenAPI 扩展字段：枚举变量名 */
+    'x-enum-varnames'?: string[];
+    /** OpenAPI 扩展字段：枚举名称 */
+    'x-enumNames'?: string[];
 }
 /**
  * Swagger项目

package/dist/utils/comment.d.ts

@@ -1,8 +1,23 @@
-import { SwaggerParameter } from '../types';
+import { ParameterInfo } from '../types';
+/**
+ * 注释生成需要的操作信息
+ */
+export interface ApiCommentOperation {
+    /** 接口摘要 */
+    summary?: string;
+    /** 接口描述 */
+    description?: string;
+    /** 是否废弃 */
+    deprecated?: boolean;
+}
+/**
+ * 注释生成需要的参数信息
+ */
+export type ApiCommentParameter = Pick<ParameterInfo, 'in' | 'description'>;
 /**
  * 生成接口注释
- * @param operation Swagger操作对象
+ * @param operation 接口操作信息
  * @param parameters 参数列表
  * @returns 注释字符串
  */
-export declare function generateApiComment(operation: any, parameters: SwaggerParameter[]): string;
+export declare function generateApiComment(operation: ApiCommentOperation, parameters: ApiCommentParameter[]): string;

package/dist/utils/comment.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateApiComment = generateApiComment;
 /**
  * 生成接口注释
- * @param operation Swagger操作对象
+ * @param operation 接口操作信息
  * @param parameters 参数列表
  * @returns 注释字符串
  */

package/dist/utils/type.d.ts

@@ -1,4 +1,4 @@
-import { SwaggerParameter } from '../types';
+import { SwaggerParameter, SwaggerSchema, SwaggerResponses } from '../types';
 /**
  * 移除联合类型中的顶层 null 类型
  * @param typeStr 类型字符串
@@ -11,29 +11,31 @@ export declare function stripNullFromUnion(typeStr: string): string;
  * @param schemas 可选的 schemas 上下文，用于查找被引用的类型定义
  * @returns TypeScript类型字符串
  */
-export declare function swaggerTypeToTsType(schema: any, schemas?: any): string;
+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): any;
-/**
- * 从 OpenAPI 参数生成 TypeScript 参数类型
- * @param parameters OpenAPI 参数数组
- * @returns TypeScript参数类型定义
- */
-export declare function generateParameterTypes(parameters: SwaggerParameter[]): string;
+export declare function swaggerParameterToSchema(parameter: SwaggerParameter): SwaggerSchema;
 /**
  * 获取响应类型
  * @param responses OpenAPI 响应对象
  * @param schemas OpenAPI components.schemas
  * @returns TypeScript类型字符串
  */
-export declare function getResponseType(responses: any, schemas?: any): string;
+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: any): any;
+export declare function getSchemaFromContent(content: Record<string, {
+    schema?: SwaggerSchema;
+}> | undefined): SwaggerSchema | undefined;

package/dist/utils/type.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripNullFromUnion = stripNullFromUnion;
 exports.swaggerTypeToTsType = swaggerTypeToTsType;
+exports.getRefName = getRefName;
 exports.swaggerParameterToSchema = swaggerParameterToSchema;
-exports.generateParameterTypes = generateParameterTypes;
 exports.getResponseType = getResponseType;
 exports.getSchemaFromContent = getSchemaFromContent;
 const naming_1 = require("./naming");
@@ -79,7 +79,7 @@ function swaggerTypeToTsType(schema, schemas) {
         const refSchema = schema.allOf.find((item) => item.$ref);
         const secondSchema = schema.allOf.find((item) => !item.$ref);
         if (refSchema && secondSchema) {
-            const refName = refSchema.$ref.split('/').pop();
+            const refName = getRefName(refSchema.$ref || '');
             const sanitizedRefName = (0, naming_1.sanitizeTypeName)(refName || '');
             if (secondSchema.properties) {
                 const propertyTypes = [];
@@ -132,7 +132,7 @@ function swaggerTypeToTsType(schema, schemas) {
         }
     }
     else if (schema.$ref) {
-        const refName = schema.$ref.split('/').pop();
+        const refName = getRefName(schema.$ref);
         baseType = (0, naming_1.sanitizeTypeName)(refName || 'any');
         if (schemas && refName) {
             const referencedSchema = schemas[refName];
@@ -145,7 +145,7 @@ function swaggerTypeToTsType(schema, schemas) {
         const itemSchema = schema.items;
         const itemType = swaggerTypeToTsType(itemSchema, schemas);
         if (itemSchema?.$ref && schemas) {
-            const refName = itemSchema.$ref.split('/').pop();
+            const refName = getRefName(itemSchema.$ref);
             const referencedSchema = refName ? schemas[refName] : undefined;
             baseType =
                 referencedSchema?.type === 'array' ? itemType : `${itemType}[]`;
@@ -211,6 +211,14 @@ function swaggerTypeToTsType(schema, schemas) {
     }
     return baseType;
 }
+/**
+ * 从 $ref 字符串中提取引用名称
+ * @param ref OpenAPI $ref 字符串
+ * @returns 引用名称
+ */
+function getRefName(ref) {
+    return ref.split('/').pop() || '';
+}
 /**
  * 将枚举值转换为 TypeScript 字面量类型
  * @param value 枚举值
@@ -239,41 +247,6 @@ function swaggerParameterToSchema(parameter) {
         enum: parameter.enum
     };
 }
-/**
- * 从 OpenAPI 参数生成 TypeScript 参数类型
- * @param parameters OpenAPI 参数数组
- * @returns TypeScript参数类型定义
- */
-function generateParameterTypes(parameters) {
-    if (!parameters || parameters.length === 0) {
-        return '';
-    }
-    const queryParams = parameters.filter((param) => param.in === 'query');
-    const pathParams = parameters.filter((param) => param.in === 'path');
-    const bodyParams = parameters.filter((param) => param.in === 'body');
-    const types = [];
-    if (pathParams.length > 0) {
-        const pathType = pathParams
-            .map((param) => `${param.name}: ${swaggerTypeToTsType(swaggerParameterToSchema(param))}`)
-            .join(', ');
-        types.push(`pathParams: { ${pathType} }`);
-    }
-    if (queryParams.length > 0) {
-        const queryType = queryParams
-            .map((param) => {
-            const optional = param.required ? '' : '?';
-            return `${param.name}${optional}: ${swaggerTypeToTsType(swaggerParameterToSchema(param))}`;
-        })
-            .join(', ');
-        types.push(`queryParams${queryParams.every((param) => !param.required) ? '?' : ''}: { ${queryType} }`);
-    }
-    if (bodyParams.length > 0) {
-        const bodyParam = bodyParams[0];
-        const bodyType = swaggerTypeToTsType(bodyParam.schema);
-        types.push(`data: ${bodyType}`);
-    }
-    return types.join(', ');
-}
 /**
  * 获取响应类型
  * @param responses OpenAPI 响应对象

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "swagger2api-v3",
-  "version": "1.1.8",
-  "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",
@@ -54,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": {