swagger2api-v3 1.1.7 → 1.1.9

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@
  * Swagger配置接口
  */
 export interface SwaggerConfig {
+    /** 本地 JSON Schema 路径，用于编辑器提示 */
+    $schema?: string;
     /** Swagger JSON 文件路径或 URL */
     input: string;
     /** 输出目录 */
@@ -33,65 +35,96 @@ export interface SwaggerConfig {
     methodNameIgnorePrefix?: string[];
     /** 是否在生成的方法名中添加 HTTP method 后缀，默认为 true。true: userListPost, false: userList */
     addMethodSuffix?: boolean;
+    /** 接口过滤配置 */
+    filter?: FilterConfig;
+    /** 自定义生成文件头部注释 */
+    headerComment?: string;
+}
+/**
+ * 接口过滤配置
+ */
+export interface FilterConfig {
+    /** 包含规则 */
+    include?: TagFilterConfig;
+    /** 排除规则 */
+    exclude?: TagFilterConfig;
+}
+/**
+ * 标签过滤配置
+ */
+export interface TagFilterConfig {
+    /** 需要匹配的标签名称 */
+    tags?: string[];
 }
 /**
  * 标签分组配置
  */
 export interface TagGroupingConfig {
     /** 启用标签分组 */
-    enabled: boolean;
+    enabled?: boolean;
     /** 为每个标签创建子目录 */
-    createSubDirectories: boolean;
+    createSubDirectories?: boolean;
     /** 文件命名方式 */
-    fileNaming: 'tag' | 'kebab-case' | 'camelCase';
+    fileNaming?: 'tag' | 'kebab-case' | 'camelCase';
 }
 /**
  * 生成选项
  */
 export interface GenerationOptions {
     /** 是否生成数据模型 */
-    generateModels: boolean;
+    generateModels?: boolean;
     /** 是否生成 API 接口 */
-    generateApis: boolean;
+    generateApis?: boolean;
     /** 是否生成入口文件 */
-    generateIndex: boolean;
+    generateIndex?: boolean;
     /** 是否使用 Axios */
-    useAxios: boolean;
+    useAxios?: boolean;
     /** 是否添加详细注释 */
-    addComments: boolean;
+    addComments?: boolean;
     /** 是否格式化代码 */
-    prettify: boolean;
+    prettify?: boolean;
 }
 /**
  * 注释配置
  */
 export interface CommentConfig {
     /** 包含接口描述 */
-    includeDescription: boolean;
+    includeDescription?: boolean;
     /** 包含参数信息 */
-    includeParameters: boolean;
+    includeParameters?: boolean;
     /** 包含返回值信息 */
-    includeResponses: boolean;
+    includeResponses?: boolean;
     /** 包含示例 */
-    includeExamples: boolean;
+    includeExamples?: boolean;
 }
 /**
- * Swagger文档结构
+ * OpenAPI 文档结构
  */
 export interface SwaggerDocument {
-    swagger?: string;
-    openapi?: string;
+    openapi: string;
     info: SwaggerInfo;
-    host?: string;
-    basePath?: string;
-    schemes?: string[];
-    consumes?: string[];
-    produces?: string[];
+    servers?: OpenAPIServer[];
     paths: SwaggerPaths;
-    definitions?: SwaggerDefinitions;
     components?: SwaggerComponents;
     tags?: SwaggerTag[];
 }
+/**
+ * OpenAPI Server 对象
+ */
+export interface OpenAPIServer {
+    /** Server URL */
+    url: string;
+    /** Server 描述 */
+    description?: string;
+    /** Server URL 变量 */
+    variables?: {
+        [name: string]: {
+            default: string;
+            enum?: string[];
+            description?: string;
+        };
+    };
+}
 /**
  * Swagger信息
  */
@@ -145,8 +178,6 @@ export interface SwaggerOperation {
     summary?: string;
     description?: string;
     operationId?: string;
-    consumes?: string[];
-    produces?: string[];
     parameters?: SwaggerParameter[];
     requestBody?: SwaggerRequestBody;
     responses: SwaggerResponses;
@@ -156,6 +187,8 @@ export interface SwaggerOperation {
  * Swagger请求体 (OpenAPI 3.0)
  */
 export interface SwaggerRequestBody {
+    /** 本地引用路径 */
+    $ref?: string;
     description?: string;
     content: {
         [mediaType: string]: {
@@ -169,11 +202,13 @@ export interface SwaggerRequestBody {
     required?: boolean;
 }
 /**
- * Swagger参数
+ * OpenAPI 参数
  */
 export interface SwaggerParameter {
+    /** 本地引用路径 */
+    $ref?: string;
     name: string;
-    in: 'query' | 'header' | 'path' | 'formData' | 'body';
+    in: 'query' | 'header' | 'path' | 'body' | 'cookie';
     description?: string;
     required?: boolean;
     type?: string;
@@ -184,17 +219,25 @@ export interface SwaggerParameter {
     default?: any;
 }
 /**
- * Swagger响应
+ * OpenAPI 响应
  */
 export interface SwaggerResponses {
     [statusCode: string]: SwaggerResponse;
 }
 /**
- * Swagger响应项
+ * OpenAPI 响应项
  */
 export interface SwaggerResponse {
     description: string;
-    schema?: SwaggerSchema;
+    content?: {
+        [mediaType: string]: {
+            schema?: SwaggerSchema;
+            example?: any;
+            examples?: {
+                [name: string]: any;
+            };
+        };
+    };
     headers?: {
         [name: string]: SwaggerHeader;
     };
@@ -214,10 +257,10 @@ export interface SwaggerHeader {
     default?: any;
 }
 /**
- * Swagger模式
+ * OpenAPI Schema
  */
 export interface SwaggerSchema {
-    type?: string;
+    type?: string | string[];
     format?: string;
     title?: string;
     description?: string;
@@ -243,6 +286,10 @@ export interface SwaggerSchema {
     externalDocs?: SwaggerExternalDocs;
     nullable?: boolean;
     deprecated?: boolean;
+    /** OpenAPI 扩展字段：枚举变量名 */
+    'x-enum-varnames'?: string[];
+    /** OpenAPI 扩展字段：枚举名称 */
+    'x-enumNames'?: string[];
 }
 /**
  * Swagger项目
@@ -255,12 +302,6 @@ export interface SwaggerItems {
     default?: any;
     $ref?: string;
 }
-/**
- * Swagger定义
- */
-export interface SwaggerDefinitions {
-    [name: string]: SwaggerSchema;
-}
 /**
  * Swagger组件 (OpenAPI 3.0)
  */
@@ -348,7 +389,7 @@ export interface ParameterInfo {
     /** 参数类型 */
     type: string;
     /** 参数位置 */
-    in: 'query' | 'header' | 'path' | 'formData' | 'body';
+    in: 'query' | 'header' | 'path' | 'body' | 'cookie';
     /** 是否必需 */
     required: boolean;
     /** 参数描述 */

package/dist/utils/comment.d.ts

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

package/dist/utils/comment.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateApiComment = generateApiComment;
+/**
+ * 生成接口注释
+ * @param operation 接口操作信息
+ * @param parameters 参数列表
+ * @returns 注释字符串
+ */
+function generateApiComment(operation, parameters) {
+    const comments = ['/**'];
+    if (operation.summary) {
+        comments.push(` * ${operation.summary}`);
+    }
+    if (operation.description && operation.description !== operation.summary) {
+        comments.push(` * ${operation.description}`);
+    }
+    if (parameters && parameters.length > 0) {
+        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 hasParams = queryParams.length > 0 || pathParams.length > 0;
+        const hasData = bodyParams.length > 0;
+        if (hasParams || hasData) {
+            comments.push(' *');
+            if (hasParams) {
+                const paramDescriptions = [...pathParams, ...queryParams]
+                    .map((param) => param.description || '')
+                    .filter((description) => description)
+                    .join(', ');
+                const description = paramDescriptions || '请求参数';
+                comments.push(` * @param params ${description}`);
+            }
+            if (hasData) {
+                const dataParam = bodyParams[0];
+                const description = dataParam?.description || '请求数据';
+                comments.push(` * @param data ${description}`);
+            }
+            comments.push(` * @param config 可选的请求配置`);
+        }
+    }
+    if (operation.deprecated) {
+        comments.push(' * @deprecated');
+    }
+    comments.push(' */');
+    return comments.join('\n');
+}

package/dist/utils/file.d.ts

@@ -0,0 +1,23 @@
+import { SwaggerDocument } from '../types';
+/**
+ * 确保目录存在，如果不存在则创建
+ * @param dirPath 目录路径
+ */
+export declare function ensureDirectoryExists(dirPath: string): void;
+/**
+ * 删除目录及其所有内容
+ * @param dirPath 目录路径
+ */
+export declare function removeDirectory(dirPath: string): void;
+/**
+ * 读取Swagger文档
+ * @param input 文件路径或URL
+ * @returns Swagger文档对象
+ */
+export declare function loadSwaggerDocument(input: string): Promise<SwaggerDocument>;
+/**
+ * 写入文件
+ * @param filePath 文件路径
+ * @param content 文件内容
+ */
+export declare function writeFile(filePath: string, content: string): void;

package/dist/utils/file.js

@@ -0,0 +1,98 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureDirectoryExists = ensureDirectoryExists;
+exports.removeDirectory = removeDirectory;
+exports.loadSwaggerDocument = loadSwaggerDocument;
+exports.writeFile = writeFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const axios_1 = __importDefault(require("axios"));
+/**
+ * 确保目录存在，如果不存在则创建
+ * @param dirPath 目录路径
+ */
+function ensureDirectoryExists(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * 删除目录及其所有内容
+ * @param dirPath 目录路径
+ */
+function removeDirectory(dirPath) {
+    if (fs.existsSync(dirPath)) {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+    }
+}
+/**
+ * 读取Swagger文档
+ * @param input 文件路径或URL
+ * @returns Swagger文档对象
+ */
+async function loadSwaggerDocument(input) {
+    try {
+        if (input.startsWith('http://') || input.startsWith('https://')) {
+            const { data } = await axios_1.default.get(input);
+            console.log('Loaded from URL:', input);
+            if (data.components?.schemas) {
+                console.log('Schemas count:', Object.keys(data.components.schemas).length);
+            }
+            else {
+                console.log('No schemas in loaded data');
+            }
+            return data;
+        }
+        const content = fs.readFileSync(input, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to load Swagger document from ${input}: ${error}`);
+    }
+}
+/**
+ * 写入文件
+ * @param filePath 文件路径
+ * @param content 文件内容
+ */
+function writeFile(filePath, content) {
+    const dir = path.dirname(filePath);
+    ensureDirectoryExists(dir);
+    fs.writeFileSync(filePath, content, 'utf-8');
+}

package/dist/utils/index.d.ts

@@ -1,99 +1,4 @@
-import { SwaggerDocument, SwaggerParameter } from '../types';
-/**
- * 工具函数集合
- */
-/**
- * 将路径转换为小驼峰命名的函数名
- * @param method HTTP方法
- * @param path 接口路径
- * @returns 小驼峰命名的函数名
- */
-export declare function pathToFunctionName(method: string, path: string): string;
-/**
- * 将字符串转换为kebab-case
- * @param str 输入字符串
- * @returns kebab-case字符串
- */
-export declare function toKebabCase(str: string): string;
-/**
- * 将字符串转换为PascalCase
- * @param str 输入字符串
- * @returns PascalCase字符串
- */
-export declare function toPascalCase(str: string): string;
-/**
- * 将字符串转换为camelCase
- * @param str 输入字符串
- * @returns camelCase字符串
- */
-export declare function toCamelCase(str: string): string;
-/**
- * 从方法名中移除指定的前缀
- * @param methodName 方法名
- * @param prefixes 需要移除的前缀数组
- * @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;
-export declare function stripNullFromUnion(typeStr: string): string;
-/**
- * 将Swagger类型转换为TypeScript类型
- * @param schema Swagger模式
- * @param schemas 可选的 schemas 上下文,用于查找被引用的类型定义
- * @returns TypeScript类型字符串
- */
-export declare function swaggerTypeToTsType(schema: any, schemas?: any): string;
-/**
- * 从Swagger参数生成TypeScript参数类型
- * @param parameters Swagger参数数组
- * @returns TypeScript参数类型定义
- */
-export declare function generateParameterTypes(parameters: SwaggerParameter[]): string;
-/**
- * 确保目录存在，如果不存在则创建
- * @param dirPath 目录路径
- */
-export declare function ensureDirectoryExists(dirPath: string): void;
-/**
- * 删除目录及其所有内容
- * @param dirPath 目录路径
- */
-export declare function removeDirectory(dirPath: string): void;
-/**
- * 读取Swagger文档
- * @param input 文件路径或URL
- * @returns Swagger文档对象
- */
-export declare function loadSwaggerDocument(input: string): Promise<SwaggerDocument>;
-/**
- * 写入文件
- * @param filePath 文件路径
- * @param content 文件内容
- */
-export declare function writeFile(filePath: string, content: string): void;
-/**
- * 生成接口注释
- * @param operation Swagger操作对象
- * @param parameters 参数列表
- * @returns 注释字符串
- */
-export declare function generateApiComment(operation: any, parameters: SwaggerParameter[]): string;
-/**
- * 清理文件名，移除非法字符
- * @param filename 文件名
- * @returns 清理后的文件名
- */
-export declare function sanitizeFilename(filename: string): string;
-/**
- * 获取响应类型
- * @param responses Swagger响应对象
- * @returns TypeScript类型字符串
- */
-export declare function getResponseType(responses: any): string;
-export declare function sanitizeTypeName(name: string): string;
+export * from './naming';
+export * from './type';
+export * from './file';
+export * from './comment';