XY Swagger Generator

基于 Swagger/OpenAPI 的 Dart/Flutter API/模型代码生成工具。

✨ 功能特性

🚀 核心功能

• 完整的 OpenAPI 3.0 支持：涵盖所有主要规范特性
• 高性能解析：支持并行解析和流式处理大型文档
• 智能代码生成：生成高质量的 Dart/Flutter 代码
• 模块化架构：按 API 模块自动分组生成

🎯 专为 Flutter 优化

• Dio + Retrofit 集成：完美适配主流网络架构
• 类型安全：生成强类型的 API 接口和模型
• JSON 序列化：自动生成 json_serializable 代码
• String 默认值：自动为 String 类型字段添加默认值，提升容错性
• 文件上传支持：完整的 multipart/form-data 支持

🔧 高级特性

• 智能缓存：提升重复操作性能
• 错误诊断：详细的错误报告和修复建议
• 性能监控：内置性能统计和优化
• 增量生成：支持增量更新和变更检测

📚 文档和规范

核心文档

• 代码生成规范 - 完整的生成规范和最佳实践
• 快速参考指南 - 常见问题和解决方案
• 代码审查清单 - 质量保证检查清单
• 生成器配置 - 详细的配置选项

设计原则

1. OpenAPI 3.0 标准优先 - 严格遵循规范，不进行主观推断
2. 与服务器保持一致 - swagger.json 是唯一真实来源
3. 有问题沟通文档 - 发现问题时要求完善后端文档
4. 类型安全第一 - 生成强类型代码，避免运行时错误

🚀 快速开始

📦 作为 dev_dependencies 使用（推荐）

本工具可以作为 dev_dependencies 集成到您的 Flutter/Dart 项目中：

1. 添加依赖

在您的项目 pubspec.yaml 中添加：

dev_dependencies:
  swagger_generator_flutter:
    git:
      url: https://github.com/your-org/swagger_generator_flutter.git
      ref: develop
  
  # 或使用本地路径（开发时）
  # swagger_generator_flutter:
  #   path: ../swagger_generator_flutter

2. 创建配置文件

复制 generator_config.template.yaml 到您的项目根目录，重命名为 generator_config.yaml 并修改配置。

3. 执行代码生成

# 安装依赖
flutter pub get

# 生成所有文件
dart run swagger_generator_flutter generate --all

# 生成 .g.dart 文件
dart run build_runner build --delete-conflicting-outputs

📖 详细使用说明：查看 作为 dev_dependencies 使用指南

---

💻 独立项目使用

如果您想直接在本项目中开发和测试：

1. 安装依赖

flutter pub get

2. 基础用法（命令行）

# 生成模型和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

# 只生成指定 tags 的 API 和模型
dart run bin/main.dart generate --all --included-tags=User,Pet,Store

3. 编程式用法（推荐）

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}');
}

📖 详细配置

CLI 命令选项

基本选项

• --all / -a: 生成所有文件（API + 模型 + 文档）
• --api / -r: 只生成 Retrofit 风格 API 接口
• --models / -m: 只生成数据模型
• --docs / -d: 只生成 API 文档
• --simple / -s: 使用简洁版模型生成
• --split-by-tags / -t: 按 tags 分组生成多个 API 文件（默认启用）
• --output-dir / -o: 指定输出目录（默认：generator）

高级选项

• --included-tags / -i: 只生成指定 tags 的 API 和模型
• --excluded-tags / -e: 从生成中排除指定的 tags

示例：

# 只生成 User 和 Pet 相关的 API 和模型
dart run swagger_generator_flutter generate --all --included-tags=User,Pet

# 只生成 Store 相关的 API
dart run swagger_generator_flutter generate --api --included-tags=Store

# 生成多个指定 tags
dart run swagger_generator_flutter generate --all -i User,Pet,Order,Payment

行为说明：

• 如果某个 endpoint 有多个 tags，只要其中一个 tag 在 included_tags 列表中，就会生成该 endpoint
• 只生成被选中的 endpoints 所引用的 models，避免生成未使用的 model 代码
• 与 split-by-tags 选项完全兼容

配置文件选项

API Client 配置

可以在 generator_config.yaml 中自定义主 API 客户端的类名和文件名：

generation:
  api:
    enabled: true
    use_retrofit: true
    use_dio: true

    # API Client 配置
    client:
      class_name: "ApiClient"        # API 客户端类名（默认: ApiClient）
      file_name: "api_client"        # API 客户端文件名（默认: api_client）

使用场景：

• 多项目/模块：避免命名冲突，如 ShopApiClient、UserApiClient
• 项目规范：符合团队命名规范，如 AppApiService、NetworkClient
• 模块化开发：按模块划分，如 PaymentModuleApi、OrderModuleApi

示例：

# 示例 1: 电商项目
client:
  class_name: "ShopApiClient"
  file_name: "shop_api_client"

# 示例 2: 用户模块
client:
  class_name: "UserModuleApi"
  file_name: "user_module_api"

# 示例 3: 应用级 API
client:
  class_name: "AppApiService"
  file_name: "app_api_service"

生成结果：

// 文件: lib/generated/api/shop_api_client.dart
class ShopApiClient {
  final Dio _dio;

  ShopApiClient(this._dio) {
    _initApis();
  }

  // ... API 方法
}

📖 更多示例：查看 API Client 配置示例

生成器类型

1. RetrofitApiGenerator（基础版）

final generator = RetrofitApiGenerator(
  className: 'ApiService',        // 生成的类名
  splitByTags: true,             // 是否按标签分割（默认启用）
  useRetrofit: true,             // 使用 Retrofit 注解
  generateModels: true,          // 生成模型类
);

2. OptimizedRetrofitGenerator（推荐）

final generator = OptimizedRetrofitGenerator(
  className: 'ApiService',
  generateModularApis: true,     // 模块化 API
  generateBaseResult: true,      // 基础响应类型
  generatePagination: true,      // 分页支持
  generateFileUpload: true,      // 文件上传
  baseResultType: 'BaseResult',  // 自定义基础类型
  pageResultType: 'PageResult',  // 自定义分页类型
);

3. PerformanceGenerator（高性能）

final generator = PerformanceGenerator(
  maxConcurrency: 4,             // 最大并发数
  enableCaching: true,           // 启用缓存
  enableIncremental: true,       // 增量生成
  enableParallel: true,          // 并行生成
);

解析器配置

final parser = PerformanceParser(
  config: ParseConfig(
    enableParallelParsing: true,   // 并行解析
    enableStreamParsing: false,    // 流式解析
    enableCaching: true,           // 缓存
    maxConcurrency: 4,             // 最大并发数
    enablePerformanceStats: true,  // 性能统计
  ),
);

验证和错误处理

// 创建验证器
final validator = EnhancedValidator(
  strictMode: false,             // 严格模式
  includeWarnings: true,         // 包含警告
);

// 验证文档
final isValid = validator.validateDocument(document);

// 获取错误报告
final errorReport = validator.errorReporter.generateReport();
print(errorReport);

📊 性能优化

缓存策略

// 配置智能缓存
final cache = SmartCache<String>(
  maxSize: 1000,                 // 最大缓存大小
  strategy: CacheStrategy.smart, // 缓存策略
  defaultTtl: Duration(hours: 1), // 默认过期时间
);

// 获取缓存统计
final stats = cache.getStats();
print('缓存命中率: ${(stats.hitRate * 100).toStringAsFixed(1)}%');

性能监控

// 获取解析性能统计
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 源文件

运行测试

dart run test tests/

🎯 规范遵循示例

✅ 正确的生成结果

// 严格按照 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();

❌ 避免的错误做法

// 错误：生成不存在的类型
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';

贡献指南

• 严格遵循 代码生成规范
• 使用 代码审查清单 进行质量检查
• 代码需包含中英文注释
• 新增功能请补充对应测试用例
• 生成规则/命名风格如有特殊需求请在 issue 说明

常见问题

• 生成的类型不存在？ 检查 swagger.json 中是否定义了对应的 schema
• 接口缺少参数？ 确认 swagger.json 中是否有完整的参数定义
• 可空性不正确？ 检查 swagger.json 中的 nullable 字段设置
• 更多问题请参考 快速参考指南

脚本命令说明

Linux/macOS (run_swagger.sh)

# 显示帮助
./run_swagger.sh help

# 只生成数据模型
./run_swagger.sh models

# 只生成API文档
./run_swagger.sh docs

# 只生成Retrofit API
./run_swagger.sh api

Windows (run_swagger.bat)

# 显示帮助
run_swagger.bat help

# 只生成数据模型
run_swagger.bat models

# 只生成API文档
run_swagger.bat docs

# 只生成Retrofit API
run_swagger.bat api

---

更新日期：2025-07-13
作者：Max