swagger_generator_flutter/docs/API_REFERENCE.md

API 参考文档

本文档详细介绍了 Swagger Generator Flutter 的所有 API 接口和配置选项。

目录

• 核心类
• 生成器
• 解析器
• 验证器
• 缓存系统
• 配置选项

核心类

SwaggerDocument

OpenAPI 文档的主要数据模型。

class SwaggerDocument {
  final String title;
  final String version;
  final String description;
  final List<ApiServer> servers;
  final Map<String, ApiPath> paths;
  final Map<String, ApiModel> models;
  final ApiComponents components;
  final List<ApiSecurityRequirement> security;
  
  SwaggerDocument({
    required this.title,
    required this.version,
    required this.description,
    required this.servers,
    required this.paths,
    required this.models,
    required this.components,
    required this.security,
  });
  
  factory SwaggerDocument.fromJson(Map<String, dynamic> json);
  Map<String, dynamic> toJson();
}

ApiPath

API 路径和操作的定义。

class ApiPath {
  final String path;
  final HttpMethod method;
  final String summary;
  final String description;
  final String operationId;
  final List<String> tags;
  final List<ApiParameter> parameters;
  final ApiRequestBody? requestBody;
  final Map<String, ApiResponse> responses;
  final List<ApiSecurityRequirement> security;
  
  ApiPath({
    required this.path,
    required this.method,
    required this.summary,
    required this.description,
    required this.operationId,
    required this.tags,
    required this.parameters,
    this.requestBody,
    required this.responses,
    required this.security,
  });
}

ApiModel

数据模型的定义。

class ApiModel {
  final String name;
  final String description;
  final Map<String, ApiProperty> properties;
  final List<String> required;
  
  ApiModel({
    required this.name,
    required this.description,
    required this.properties,
    required this.required,
  });
}

生成器

BaseGenerator

所有生成器的基类。

abstract class BaseGenerator {
  String get generatorType;
  String generate();
}

RetrofitApiGenerator

基础的 Retrofit API 生成器。

class RetrofitApiGenerator extends BaseGenerator {
  final String className;
  final bool splitByTags;
  final bool useRetrofit;
  final bool generateModels;
  
  RetrofitApiGenerator({
    this.className = 'ApiService',
    this.splitByTags = false,
    this.useRetrofit = true,
    this.generateModels = true,
  });
  
  @override
  String generateFromDocument(SwaggerDocument document);
}

方法

• generateFromDocument(SwaggerDocument document): 从文档生成代码
• generateSingleApiFile(): 生成单个 API 文件
• generateMainApiFile(): 生成主 API 文件（分模块时）

OptimizedRetrofitGenerator

优化版的 Retrofit API 生成器。

class OptimizedRetrofitGenerator extends BaseGenerator {
  final String className;
  final bool generateModularApis;
  final bool generateBaseResult;
  final bool generatePagination;
  final bool generateFileUpload;
  final String baseResultType;
  final String pageResultType;
  
  OptimizedRetrofitGenerator({
    this.className = 'ApiService',
    this.generateModularApis = true,
    this.generateBaseResult = true,
    this.generatePagination = true,
    this.generateFileUpload = true,
    this.baseResultType = 'BaseResult',
    this.pageResultType = 'BasePageResult',
  });
}

特性

• 模块化生成: 按 API 标签自动分组
• 基础类型: 生成 BaseResult、BasePageResult 等
• 文件上传: 支持 multipart/form-data
• 工具类: 生成 ApiUtils 工具类

PerformanceGenerator

高性能代码生成器。

class PerformanceGenerator extends BaseGenerator {
  final int maxConcurrency;
  final bool enableCaching;
  final bool enableIncremental;
  final bool enableParallel;
  
  PerformanceGenerator({
    this.maxConcurrency = 4,
    this.enableCaching = true,
    this.enableIncremental = true,
    this.enableParallel = true,
  });
  
  Future<String> generateFromDocument(SwaggerDocument document);
  GenerationStats getStats();
  CacheStats getCacheStats();
  void clearCache();
}

方法

• generateFromDocument(): 异步生成代码
• getStats(): 获取生成性能统计
• getCacheStats(): 获取缓存统计
• clearCache(): 清除缓存

解析器

PerformanceParser

高性能 OpenAPI 解析器。

class PerformanceParser {
  final ParseConfig config;
  
  PerformanceParser({ParseConfig? config});
  
  Future<SwaggerDocument> parseDocument(String jsonString);
  ParsePerformanceStats? get lastStats;
  void clearCache();
  Map<String, dynamic> getCacheStats();
}

ParseConfig

解析器配置。

class ParseConfig {
  final bool enableParallelParsing;
  final bool enableStreamParsing;
  final bool enableIncrementalParsing;
  final bool enableCaching;
  final int maxConcurrency;
  final int streamBufferSize;
  final bool enablePerformanceStats;
  final bool enableMemoryOptimization;
  
  const ParseConfig({
    this.enableParallelParsing = true,
    this.enableStreamParsing = false,
    this.enableIncrementalParsing = false,
    this.enableCaching = true,
    this.maxConcurrency = 4,
    this.streamBufferSize = 8192,
    this.enablePerformanceStats = false,
    this.enableMemoryOptimization = true,
  });
}

验证器

EnhancedValidator

增强的文档验证器。

class EnhancedValidator {
  final bool strictMode;
  final bool includeWarnings;
  
  EnhancedValidator({
    this.strictMode = false,
    this.includeWarnings = true,
  });
  
  bool validateDocument(SwaggerDocument document);
  ErrorReporter get errorReporter;
}

ErrorReporter

错误报告器。

class ErrorReporter {
  List<DetailedError> get errors;
  bool get hasErrors;
  bool get hasCriticalErrors;
  
  void addError(DetailedError error);
  void reportError({
    required String id,
    required String title,
    required String description,
    required ErrorSeverity severity,
    required ErrorCategory category,
    required String jsonPath,
    // ... 其他参数
  });
  
  List<DetailedError> getErrorsBySeverity(ErrorSeverity severity);
  List<DetailedError> getErrorsByCategory(ErrorCategory category);
  Map<ErrorSeverity, int> getErrorStatistics();
  
  String generateReport({
    bool includeStatistics = true,
    bool groupByCategory = false,
    ErrorSeverity? minSeverity,
  });
  
  String generateJsonReport();
  void clear();
}

缓存系统

SmartCache

智能缓存管理器。

class SmartCache<T> {
  final int maxSize;
  final CacheStrategy strategy;
  final Duration defaultTtl;
  
  SmartCache({
    int maxSize = 1000,
    CacheStrategy strategy = CacheStrategy.smart,
    Duration defaultTtl = const Duration(hours: 1),
  });
  
  T? get(String key);
  void put(String key, T value, {Duration? ttl, String? etag});
  bool containsKey(String key);
  T? remove(String key);
  void clear();
  
  CacheStats getStats();
  List<String> getKeysNeedingRefresh();
  Future<void> refreshKeys(List<String> keys, Future<T> Function(String key) refreshFunction);
  Future<void> warmUp(Map<String, Future<T> Function()> warmUpFunctions);
}

CacheStrategy

缓存策略枚举。

enum CacheStrategy {
  lru,    // 最近最少使用
  lfu,    // 最近最常使用
  fifo,   // 先进先出
  ttl,    // 基于时间的过期
  smart,  // 智能策略
}

配置选项

生成器配置

选项	类型	默认值	描述
className	String	'ApiService'	生成的主类名
splitByTags	bool	true	是否按标签分割 API
generateModularApis	bool	true	生成模块化 API
generateBaseResult	bool	true	生成基础响应类型
generatePagination	bool	true	生成分页支持
generateFileUpload	bool	true	生成文件上传支持
baseResultType	String	'BaseResult'	基础响应类型名
pageResultType	String	'BasePageResult'	分页响应类型名

解析器配置

选项	类型	默认值	描述
enableParallelParsing	bool	true	启用并行解析
enableStreamParsing	bool	false	启用流式解析
enableCaching	bool	true	启用缓存
maxConcurrency	int	4	最大并发数
enablePerformanceStats	bool	false	启用性能统计

验证器配置

选项	类型	默认值	描述
strictMode	bool	false	严格模式
includeWarnings	bool	true	包含警告

错误类型

ErrorSeverity

enum ErrorSeverity {
  info,     // 信息
  warning,  // 警告
  error,    // 错误
  critical, // 严重错误
}

ErrorCategory

enum ErrorCategory {
  syntax,        // 语法错误
  schema,        // Schema 错误
  reference,     // 引用错误
  validation,    // 验证错误
  compatibility, // 兼容性问题
  performance,   // 性能问题
  security,      // 安全问题
  bestPractice,  // 最佳实践
}

性能统计

ParsePerformanceStats

解析性能统计。

class ParsePerformanceStats {
  final Duration totalTime;
  final Duration parseTime;
  final Duration validationTime;
  final Duration modelCreationTime;
  final int memoryUsage;
  final int documentSize;
  final int pathCount;
  final int schemaCount;
  
  double get pathsPerSecond;
  double get schemasPerSecond;
  double get bytesPerSecond;
}

GenerationStats

生成性能统计。

class GenerationStats {
  final int totalTasks;
  final int completedTasks;
  final int failedTasks;
  final Duration totalTime;
  final Duration averageTaskTime;
  final int linesGenerated;
  final int bytesGenerated;
  final double parallelEfficiency;
  
  double get successRate;
  double get linesPerSecond;
  double get bytesPerSecond;
}