295 lines
8.2 KiB
Markdown
295 lines
8.2 KiB
Markdown
# XY Swagger Generator
|
||
|
||
基于 Swagger/OpenAPI 的 Dart/Flutter API/模型代码生成工具。
|
||
|
||
[](https://dart.dev/)
|
||
[](https://flutter.dev/)
|
||
[](https://spec.openapis.org/oas/v3.0.3/)
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🚀 核心功能
|
||
- **完整的 OpenAPI 3.0 支持**：涵盖所有主要规范特性
|
||
- **高性能解析**：支持并行解析和流式处理大型文档
|
||
- **智能代码生成**：生成高质量的 Dart/Flutter 代码
|
||
- **模块化架构**：按 API 模块自动分组生成
|
||
|
||
### 🎯 专为 Flutter 优化
|
||
- **Dio + Retrofit 集成**：完美适配主流网络架构
|
||
- **类型安全**：生成强类型的 API 接口和模型
|
||
- **JSON 序列化**：自动生成 json_serializable 代码
|
||
- **文件上传支持**：完整的 multipart/form-data 支持
|
||
|
||
### 🔧 高级特性
|
||
- **智能缓存**：提升重复操作性能
|
||
- **错误诊断**：详细的错误报告和修复建议
|
||
- **性能监控**：内置性能统计和优化
|
||
- **增量生成**：支持增量更新和变更检测
|
||
|
||
## 📚 **文档和规范**
|
||
|
||
### **核心文档**
|
||
- [**代码生成规范**](./AUGMENT_CODE_GENERATION_STANDARDS.md) - 完整的生成规范和最佳实践
|
||
- [**快速参考指南**](./QUICK_REFERENCE.md) - 常见问题和解决方案
|
||
- [**代码审查清单**](./CODE_REVIEW_CHECKLIST.md) - 质量保证检查清单
|
||
- [**生成器配置**](./generator_config.yaml) - 详细的配置选项
|
||
|
||
### **设计原则**
|
||
1. **OpenAPI 3.0 标准优先** - 严格遵循规范，不进行主观推断
|
||
2. **与服务器保持一致** - swagger.json 是唯一真实来源
|
||
3. **有问题沟通文档** - 发现问题时要求完善后端文档
|
||
4. **类型安全第一** - 生成强类型代码，避免运行时错误
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
```bash
|
||
flutter pub get
|
||
```
|
||
|
||
### 2. 基础用法（命令行）
|
||
```bash
|
||
# 生成模型和API（推荐）
|
||
sh run_swagger.sh all
|
||
|
||
# 分别生成
|
||
sh run_swagger.sh api # 只生成 API
|
||
sh run_swagger.sh models # 只生成模型
|
||
|
||
# 或直接使用 dart 命令
|
||
dart run bin/main.dart generate --models --api
|
||
```
|
||
|
||
### 3. 编程式用法（推荐）
|
||
```dart
|
||
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';
|
||
|
||
void main() async {
|
||
// 使用高性能解析器
|
||
final parser = PerformanceParser(
|
||
config: ParseConfig(
|
||
enablePerformanceStats: true,
|
||
enableParallelParsing: true,
|
||
),
|
||
);
|
||
|
||
// 解析 OpenAPI 文档
|
||
final jsonString = await File('swagger.json').readAsString();
|
||
final document = await parser.parseDocument(jsonString);
|
||
|
||
// 使用优化生成器
|
||
final generator = OptimizedRetrofitGenerator(
|
||
className: 'ApiService',
|
||
generateModularApis: true,
|
||
generateBaseResult: true,
|
||
generatePagination: true,
|
||
generateFileUpload: true,
|
||
);
|
||
|
||
// 生成代码
|
||
final generatedCode = generator.generateFromDocument(document);
|
||
|
||
// 保存文件
|
||
await File('lib/api/api_service.dart').writeAsString(generatedCode);
|
||
|
||
// 查看性能统计
|
||
final stats = parser.lastStats;
|
||
print('解析时间: ${stats?.totalTime.inMilliseconds}ms');
|
||
print('生成的路径数: ${stats?.pathCount}');
|
||
}
|
||
```
|
||
|
||
## 📖 详细配置
|
||
|
||
### 生成器类型
|
||
|
||
#### 1. RetrofitApiGenerator（基础版）
|
||
```dart
|
||
final generator = RetrofitApiGenerator(
|
||
className: 'ApiService', // 生成的类名
|
||
splitByTags: true, // 是否按标签分割（默认启用）
|
||
useRetrofit: true, // 使用 Retrofit 注解
|
||
generateModels: true, // 生成模型类
|
||
);
|
||
```
|
||
|
||
#### 2. OptimizedRetrofitGenerator（推荐）
|
||
```dart
|
||
final generator = OptimizedRetrofitGenerator(
|
||
className: 'ApiService',
|
||
generateModularApis: true, // 模块化 API
|
||
generateBaseResult: true, // 基础响应类型
|
||
generatePagination: true, // 分页支持
|
||
generateFileUpload: true, // 文件上传
|
||
baseResultType: 'BaseResult', // 自定义基础类型
|
||
pageResultType: 'PageResult', // 自定义分页类型
|
||
);
|
||
```
|
||
|
||
#### 3. PerformanceGenerator（高性能）
|
||
```dart
|
||
final generator = PerformanceGenerator(
|
||
maxConcurrency: 4, // 最大并发数
|
||
enableCaching: true, // 启用缓存
|
||
enableIncremental: true, // 增量生成
|
||
enableParallel: true, // 并行生成
|
||
);
|
||
```
|
||
|
||
### 解析器配置
|
||
```dart
|
||
final parser = PerformanceParser(
|
||
config: ParseConfig(
|
||
enableParallelParsing: true, // 并行解析
|
||
enableStreamParsing: false, // 流式解析
|
||
enableCaching: true, // 缓存
|
||
maxConcurrency: 4, // 最大并发数
|
||
enablePerformanceStats: true, // 性能统计
|
||
),
|
||
);
|
||
```
|
||
|
||
### 验证和错误处理
|
||
```dart
|
||
// 创建验证器
|
||
final validator = EnhancedValidator(
|
||
strictMode: false, // 严格模式
|
||
includeWarnings: true, // 包含警告
|
||
);
|
||
|
||
// 验证文档
|
||
final isValid = validator.validateDocument(document);
|
||
|
||
// 获取错误报告
|
||
final errorReport = validator.errorReporter.generateReport();
|
||
print(errorReport);
|
||
```
|
||
|
||
## 📊 性能优化
|
||
|
||
### 缓存策略
|
||
```dart
|
||
// 配置智能缓存
|
||
final cache = SmartCache<String>(
|
||
maxSize: 1000, // 最大缓存大小
|
||
strategy: CacheStrategy.smart, // 缓存策略
|
||
defaultTtl: Duration(hours: 1), // 默认过期时间
|
||
);
|
||
|
||
// 获取缓存统计
|
||
final stats = cache.getStats();
|
||
print('缓存命中率: ${(stats.hitRate * 100).toStringAsFixed(1)}%');
|
||
```
|
||
|
||
### 性能监控
|
||
```dart
|
||
// 获取解析性能统计
|
||
final parseStats = parser.lastStats;
|
||
print('解析性能统计:');
|
||
print(' 总时间: ${parseStats?.totalTime.inMilliseconds}ms');
|
||
print(' 路径数: ${parseStats?.pathCount}');
|
||
print(' 吞吐量: ${parseStats?.bytesPerSecond.toStringAsFixed(2)} bytes/s');
|
||
```
|
||
|
||
## 📁 目录结构
|
||
```
|
||
swagger_generator_flutter/
|
||
bin/ # 命令行入口
|
||
example/ # 使用示例
|
||
generator/ # 生成的 API、模型、文档
|
||
lib/ # 生成器核心代码
|
||
core/ # 核心模型和解析器
|
||
generators/ # 代码生成器
|
||
validators/ # 文档验证器
|
||
tests/ # 单元测试和集成测试
|
||
swagger.json # OpenAPI 源文件
|
||
```
|
||
|
||
## 运行测试
|
||
```bash
|
||
dart run test tests/
|
||
```
|
||
|
||
## 🎯 **规范遵循示例**
|
||
|
||
### **✅ 正确的生成结果**
|
||
```dart
|
||
// 严格按照 swagger.json 定义生成
|
||
@POST('/api/v1/Login/userLogin')
|
||
Future<BaseResult<UserLoginResult>> userLogin(
|
||
@Body() LoginRequest request // 仅当 swagger 中明确定义时
|
||
);
|
||
|
||
// 健康检查接口
|
||
@GET('/health')
|
||
Future<BaseResult<void>> healthCheck();
|
||
|
||
// 无明确 schema 的接口
|
||
@POST('/api/v1/Action/DoSomething')
|
||
Future<BaseResult<Map<String, dynamic>>> doSomething();
|
||
```
|
||
|
||
### **❌ 避免的错误做法**
|
||
```dart
|
||
// 错误：生成不存在的类型
|
||
Future<BaseResult<TaskInfoResult>> someMethod();
|
||
|
||
// 错误：添加 swagger 中未定义的参数
|
||
@POST('/api/v1/GetUsers')
|
||
Future<BaseResult<List<User>>> getUsers(
|
||
@Body() Map<String, dynamic> request // swagger 中没有定义
|
||
);
|
||
|
||
// 错误：基于关键词推断类型
|
||
if (path.contains('login')) return 'UserLoginResult';
|
||
```
|
||
|
||
## 贡献指南
|
||
- **严格遵循 [代码生成规范](./AUGMENT_CODE_GENERATION_STANDARDS.md)**
|
||
- **使用 [代码审查清单](./CODE_REVIEW_CHECKLIST.md) 进行质量检查**
|
||
- 代码需包含中英文注释
|
||
- 新增功能请补充对应测试用例
|
||
- 生成规则/命名风格如有特殊需求请在 issue 说明
|
||
|
||
## 常见问题
|
||
- **生成的类型不存在？** 检查 swagger.json 中是否定义了对应的 schema
|
||
- **接口缺少参数？** 确认 swagger.json 中是否有完整的参数定义
|
||
- **可空性不正确？** 检查 swagger.json 中的 nullable 字段设置
|
||
- 更多问题请参考 [快速参考指南](./QUICK_REFERENCE.md)
|
||
|
||
### 脚本命令说明
|
||
|
||
#### Linux/macOS (run_swagger.sh)
|
||
```bash
|
||
# 显示帮助
|
||
./run_swagger.sh help
|
||
|
||
# 只生成数据模型
|
||
./run_swagger.sh models
|
||
|
||
# 只生成API文档
|
||
./run_swagger.sh docs
|
||
|
||
# 只生成Retrofit API
|
||
./run_swagger.sh api
|
||
```
|
||
|
||
#### Windows (run_swagger.bat)
|
||
```cmd
|
||
# 显示帮助
|
||
run_swagger.bat help
|
||
|
||
# 只生成数据模型
|
||
run_swagger.bat models
|
||
|
||
# 只生成API文档
|
||
run_swagger.bat docs
|
||
|
||
# 只生成Retrofit API
|
||
run_swagger.bat api
|
||
```
|
||
|
||
---
|
||
|
||
更新日期：2025-07-13
|
||
作者：Max |