# API 参考文档 ## 📚 核心 API 类库 ### 🔧 解析器 (Parsers) #### PerformanceParser 高性能 OpenAPI 文档解析器，支持并行处理和性能监控。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 创建解析器 final parser = PerformanceParser( config: ParseConfig( enablePerformanceStats: true, // 启用性能统计 enableParallelParsing: true, // 启用并行解析 enableCaching: true, // 启用缓存 maxConcurrency: 4, // 最大并发数 enableMemoryOptimization: true, // 内存优化 ), ); // 解析文档 final jsonString = await File('swagger.json').readAsString(); final document = await parser.parseDocument(jsonString); // 获取性能统计 final stats = parser.lastStats; print('解析时间: ${stats?.totalTime.inMilliseconds}ms'); print('路径数量: ${stats?.pathCount}'); print('吞吐量: ${stats?.bytesPerSecond.toStringAsFixed(2)} bytes/s'); ``` **主要方法:** | 方法 | 描述 | 返回类型 | |------|------|----------| | `parseDocument(String jsonString)` | 解析 OpenAPI 文档 | `Future` | | `parseDocumentFromFile(String filePath)` | 从文件解析文档 | `Future` | | `validateAndParse(String jsonString)` | 验证并解析文档 | `Future` | **配置选项:** ```dart class ParseConfig { final bool enablePerformanceStats; // 启用性能统计 final bool enableParallelParsing; // 启用并行解析 final bool enableStreamParsing; // 启用流式解析 final bool enableCaching; // 启用缓存 final int maxConcurrency; // 最大并发数 final bool enableMemoryOptimization; // 内存优化 final Duration cacheTimeout; // 缓存超时时间 } ``` --- ### 🏭 生成器 (Generators) #### RetrofitApiGenerator 基于 Retrofit 注解的 API 代码生成器，支持按 tag 拆分与多版本输出。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 创建生成器 final generator = RetrofitApiGenerator( className: 'ApiService', // API 服务类名 useRetrofit: true, // 使用 Retrofit 注解 useDio: true, // 使用 Dio splitByTags: true, // 按 tag 拆分 versionedApi: true, // 多版本输出 ); // 生成代码 final generatedCode = generator.generateFromDocument(document); // 保存到文件 await File('lib/api/api_service.dart').writeAsString(generatedCode); ``` **主要方法:** | 方法 | 描述 | 返回类型 | |------|------|----------| | `generateFromDocument(SwaggerDocument doc)` | 从文档生成代码 | `String` | | `generateModularApis(SwaggerDocument doc)` | 生成模块化 API | `Map` | | `generateModels(SwaggerDocument doc)` | 生成数据模型 | `Map` | | `generateUtils(SwaggerDocument doc)` | 生成工具类 | `String` | **配置选项:** ```dart class RetrofitApiGenerator { final String className; // 生成的类名 final bool useRetrofit; // 是否使用 Retrofit 注解 final bool useDio; // 是否使用 Dio final bool splitByTags; // 是否按 tag 拆分 final bool versionedApi; // 是否按版本输出 } ``` #### 性能生成器（已移除） 该项目已简化，移除了 PerformanceGenerator。请使用 RetrofitApiGenerator 作为主要生成器。 ```dart final generator = RetrofitApiGenerator( className: 'ApiService', useRetrofit: true, useDio: true, splitByTags: true, ); final code = generator.generateFromDocument(document); ``` --- ### ✅ 验证器 (Validators) #### EnhancedValidator 增强型文档验证器，提供详细的错误报告和修复建议。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 创建验证器 final validator = EnhancedValidator( strictMode: false, // 严格模式 includeWarnings: true, // 包含警告 enableAutoFix: true, // 启用自动修复 customRules: [ // 自定义验证规则 RequiredFieldRule(), NamingConventionRule(), ], ); // 验证文档 final isValid = validator.validateDocument(document); // 获取错误报告 final errors = validator.errorReporter.getErrorsBySeverity(ErrorSeverity.error); final warnings = validator.errorReporter.getErrorsBySeverity(ErrorSeverity.warning); // 生成详细报告 final report = validator.errorReporter.generateReport(); print(report); ``` **错误级别:** ```dart enum ErrorSeverity { critical, // 严重错误，阻止生成 error, // 错误，可能影响生成质量 warning, // 警告，建议修复 info, // 信息，仅供参考 } ``` **内置验证规则:** | 规则 | 描述 | 级别 | |------|------|------| | `SchemaValidationRule` | Schema 定义验证 | Error | | `ReferenceValidationRule` | 引用完整性验证 | Critical | | `NamingConventionRule` | 命名规范验证 | Warning | | `TypeConsistencyRule` | 类型一致性验证 | Error | | `RequiredFieldRule` | 必填字段验证 | Warning | --- ### 🗄️ 缓存管理 (Cache) 当前版本不再内置 SmartCache，请在业务侧按需实现缓存策略（如内存缓存/磁盘缓存），或使用成熟的第三方库。 --- ### 🔧 工具类 (Utils) #### StringUtils 字符串处理工具类，提供命名转换和格式化功能。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 命名转换 final camelCase = StringUtils.toCamelCase('user_name'); // userName final pascalCase = StringUtils.toPascalCase('user_name'); // UserName final snakeCase = StringUtils.toSnakeCase('userName'); // user_name // 类型转换 final dartType = StringUtils.openApiTypeToDart('integer'); // int final nullableType = StringUtils.makeNullable('String'); // String? // 文档注释生成 final comment = StringUtils.generateDocComment( 'User login endpoint', parameters: ['username', 'password'], returns: 'LoginResult', ); ``` #### FileUtils 文件操作工具类，提供安全的文件读写功能。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 安全写入文件 await FileUtils.writeStringToFile( 'lib/api/generated_api.dart', generatedCode, createDirs: true, // 自动创建目录 backup: true, // 创建备份 ); // 批量写入文件 await FileUtils.writeMultipleFiles({ 'lib/api/user_api.dart': userApiCode, 'lib/api/order_api.dart': orderApiCode, 'lib/models/user.dart': userModelCode, }); // 清理生成的文件 await FileUtils.cleanGeneratedFiles('lib/api/generated/'); ``` --- ### 📊 性能监控 (Performance) #### PerformanceMonitor 性能监控器，提供详细的性能统计和分析。 ```dart import 'package:swagger_generator_flutter/swagger_generator_flutter.dart'; // 创建监控器 final monitor = PerformanceMonitor(); // 开始监控 monitor.startOperation('parse_document'); // ... 执行操作 monitor.endOperation('parse_document'); // 获取统计信息 final stats = monitor.getOperationStats('parse_document'); print('操作次数: ${stats.count}'); print('平均耗时: ${stats.averageTime.inMilliseconds}ms'); print('最大耗时: ${stats.maxTime.inMilliseconds}ms'); // 生成性能报告 final report = monitor.generateReport(); print(report); ``` --- ## 🔄 完整使用流程 ### 基本使用流程 ```bash # 步骤 1: 生成 API 和 Freezed 模型 dart run swagger_generator_flutter generate --all # 步骤 2: 运行 build_runner 生成序列化代码 dart run build_runner build --delete-conflicting-outputs ``` ### 高级使用流程 (企业级) ```bash # 步骤 1: 生成 API 和 Freezed 模型 # 使用 --included-tags 或 --excluded-tags 过滤范围 dart run swagger_generator_flutter generate --all --excluded-tags=Internal,Debug # 步骤 2: 运行 build_runner 生成序列化代码 dart run build_runner build --delete-conflicting-outputs ``` --- ## 🔍 错误处理和调试 ### 常见错误类型 ```dart // 解析错误 try { final document = await parser.parseDocument(jsonString); } on SwaggerParseException catch (e) { print('解析错误: ${e.message}'); print('错误位置: ${e.location}'); print('修复建议: ${e.suggestion}'); } // 验证错误 try { final isValid = validator.validateDocument(document); } on ValidationException catch (e) { print('验证错误: ${e.message}'); print('错误字段: ${e.fieldPath}'); print('期望值: ${e.expectedValue}'); print('实际值: ${e.actualValue}'); } // 生成错误 try { final code = generator.generateFromDocument(document); } on CodeGenerationException catch (e) { print('生成错误: ${e.message}'); print('错误类型: ${e.errorType}'); print('相关对象: ${e.relatedObject}'); } ``` ### 调试工具 ```dart // 启用调试模式 final parser = PerformanceParser( config: ParseConfig( enableDebugMode: true, // 启用调试模式 enableVerboseLogging: true, // 详细日志 logLevel: LogLevel.debug, // 日志级别 ), ); // 性能分析 final profiler = PerformanceProfiler(); profiler.startProfiling(); // ... 执行操作 final profile = profiler.endProfiling(); print('性能分析: ${profile.summary}'); // 内存分析 final memoryAnalyzer = MemoryAnalyzer(); final usage = memoryAnalyzer.getCurrentUsage(); print('内存使用: ${usage.totalMemory}MB'); print('缓存占用: ${usage.cacheMemory}MB'); ``` --- **文档版本**: v3.0 **最后更新**: 2025-11-21 **维护者**: Max