458 lines
9.9 KiB
Markdown
458 lines
9.9 KiB
Markdown
# 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;
|
|
}
|
|
```
|