# API 参考文档

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

## 目录

- [核心类](#核心类)
- [生成器](#生成器)
- [解析器](#解析器)
- [验证器](#验证器)
- [缓存系统](#缓存系统)
- [配置选项](#配置选项)

## 核心类

### SwaggerDocument

OpenAPI 文档的主要数据模型。

```dart
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 路径和操作的定义。

```dart
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

数据模型的定义。

```dart
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

所有生成器的基类。

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

### RetrofitApiGenerator

基础的 Retrofit API 生成器。

```dart
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 生成器。

```dart
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

高性能代码生成器。

```dart
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 解析器。

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

### ParseConfig

解析器配置。

```dart
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

增强的文档验证器。

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

### ErrorReporter

错误报告器。

```dart
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

智能缓存管理器。

```dart
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

缓存策略枚举。

```dart
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

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

### ErrorCategory

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

## 性能统计

### ParsePerformanceStats

解析性能统计。

```dart
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

生成性能统计。

```dart
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;
}
```