wangyang

swagger_generator_flutter

Fork 0

9.9 KiB

Raw Blame History

XY Swagger Generator - 项目概览

📋 项目简介

XY Swagger Generator 是一个专为 Flutter 开发优化的 OpenAPI 3.0 代码生成器，旨在自动化 API 接口和数据模型的生成过程，提升开发效率并确保代码质量。

🎯 设计目标

标准化优先: 严格遵循 OpenAPI 3.0 规范，确保与后端 API 文档完全一致
类型安全: 生成强类型 Dart 代码，在编译时发现潜在问题
高性能: 支持大型 API 文档的高效解析和代码生成
企业级: 提供完整的验证、缓存、监控和错误处理机制

🏗️ 核心架构

架构层次

命令行输入
   ↓
SwaggerCLI / GenerateCommand（合并多 Swagger、处理版本与 Tag 过滤）
   ↓
配置层（ConfigRepository 为主，SwaggerConfig 静态访问保持兼容）
   ↓
获取与解析（SwaggerFetcher / SwaggerDataParser，带缓存与性能监控）
   ↓
验证层（SchemaValidator 基础规则 → EnhancedValidator 装饰增强 + ErrorReporter 渲染）
   ↓
生成器层（ModelCodeGenerator / RetrofitApiGenerator + TemplateRenderer/TemplateService）
   ↓
工具层（FileUtils / PathResolver / ReferenceResolver / StringUtils 模块化）
   ↓
落盘输出（按版本与模型类别组织）

模块关系图（简化）

flowchart TD
  CLI[CLI / main] --> GC[GenerateCommand]
  GC --> CFG[ConfigRepository]
  GC --> PF[SwaggerFetcher]
  PF --> SDP[SwaggerDataParser]
  SDP --> VAL[SchemaValidator]
  VAL -->|decorated by| EV[EnhancedValidator]
  SDP --> MODELS[Core Models]
  EV --> ER[ErrorReporter]
  GC --> GEN[Generators]
  GEN --> MC[ModelCodeGenerator]
  GEN --> RG[RetrofitApiGenerator]
  RG --> TR[TemplateRenderer]
  TR --> TS[TemplateService]
  GC --> OUT[File Output / Writer]
  subgraph Utils
    FU[FileUtils]
    PR[PathResolver]
    RR[ReferenceResolver]
    SU[StringUtils]
  end
  GEN -.-> Utils
  SDP -.-> Utils
  GC -.-> Utils

模块职责与核心类

Commands
- GenerateCommand: 解析参数、编排流程（解析→验证→生成→落盘）
Config
- ConfigRepository: 主配置入口，提供只读配置访问和缓存
- ConfigLoader: 向后兼容的静态加载器（保留，推荐迁移到 ConfigRepository）
Parsers
- SwaggerFetcher: 统一 http/file 源获取、缓存与错误处理
- SwaggerDataParser: OpenAPI 3.0 解析为内部模型
Validators
- SchemaValidator: 基础规则验证器（必留）
- EnhancedValidator: 装饰器，复用 SchemaValidator 结果并通过 ErrorReporter 渲染
- ErrorReporter: 可插拔渲染（文本/JSON/CI）
Generators
- ModelCodeGenerator: 生成模型（Freezed/json_serializable）
- RetrofitApiGenerator: 生成 API（Mustache 模板、按 tag 拆分、版本化）
- TemplateRenderer/TemplateService: 模板加载与注释/文件头生成
Utils
- FileUtils/PathResolver: 异步 IO、路径解析
- ReferenceResolver: $ref 解析与去循环
- StringUtils: 统一导出（NamingConverter/TextCleaner/TemplateService）

代码生成流程（详细）

读取配置
- 首选 ConfigRepository.loadSync()/load()，兼容 ConfigLoader
获取与解析
- SwaggerFetcher 读取（网络/本地）→ CacheManager 命中 → SwaggerDataParser 解析
校验
- SchemaValidator 执行基础校验 → EnhancedValidator 转换为结构化报告（ErrorReporter）
数据准备
- 引用解析、模型依赖裁剪、版本/Tag 分组
代码生成
- ModelCodeGenerator 产出 models
- RetrofitApiGenerator 产出 API（TemplateRenderer + 模板）
文件输出
- GenerationOutputService/ FileUtils 落盘，按版本/分类组织
总结输出
- 生成 SUMMARY.md、日志摘要、耗时统计

最近重构变更（摘自 check_list）

核心模型拆分为 models/ 子模块，路径支持 path+method 键，补齐 toJson
GenerateCommand 拆出输出服务与调度，职责更清晰
RetrofitApiGenerator 切换 Mustache 模板
Validator 体系化（ValidationRule/Context），EnhancedValidator 装饰器化
引入 ConfigRepository，PathResolver 复用路径逻辑
TypeValidator 规则化，复用 SchemaValidator 结果模型
SwaggerFetcher 异步 IO + 内容哈希缓存
FileUtils 全异步 API，统一 PathResolver
performance_parser 使用 Isolate.run 实现并行
error_rules 迁移至 YAML/JSON 配置
exceptions 拆分为 exceptions/ 子目录
error_reporter 拆分为 data/reporter/renderers，error_reporter.dart 仅作为汇总导出
StringUtils 拆分为 naming_converter/text_cleaner/template_service，主文件为统一导出接口

核心组件

1. 命令与配置

SwaggerCLI / GenerateCommand: 注册命令、展示帮助、执行生成，支持多 Swagger 合并、版本化输出、Tag 过滤和忽略列表
ConfigLoader / SwaggerConfig: 解析 generator_config.yaml，提供 swagger_urls 顺序合并、输出目录、版本提取正则、ApiClient 命名、BaseResult 导入等配置

2. 解析器 (Parsers)

SwaggerDataParser: 支持 http(s) 与 file:// 源的 OpenAPI 解析，内置缓存与性能监测，解析 controllers/tags/schema 依赖

3. 验证器 (Validators)

SchemaValidator / EnhancedValidator: 基础与增强校验器，用于在生成前验证文档一致性

4. 生成器 (Generators)

ModelCodeGenerator: 生成基于 Freezed 的不可变数据模型，自动获得 copyWith、toString、==/hashCode 等功能，并与 json_serializable 无缝集成。
RetrofitApiGenerator: 支持按 tag 拆分、多版本目录与统一 ApiClient，自动生成查询参数实体并处理版本化类名
DocumentationGenerator: 输出 Markdown API 文档与统计摘要

5. 工具类 (Utils)

CacheManager / PerformanceMonitor: 缓存解析结果并记录耗时
FileUtils / StringUtils: 路径解析（基于配置文件目录）、命名转换、文件写入等

🔧 技术特性

生成行为

支持按顺序合并多个 swagger_urls，后者覆盖前者（适合 v1→v2 升级）
版本化输出：路径按版本分目录，v2+ 类名自动追加 V2/V3 后缀，统一 ApiClient 聚合各版本
Tag 过滤与模型裁剪：included_tags/excluded_tags 与依赖分析确保只生成实际使用的模型
分页识别：检测 total/items 模式并替换为 BasePageResult<T>，包装在 BaseResult
查询参数实体：GET 查询参数超过 4 个时自动生成 parameters 类，集中导出
忽略列表与相对路径：ignored_directories/files 控制落盘，路径基于配置文件所在目录解析
BaseResult/BasePageResult 导入可配置，模型导出自动补全统一的 index.dart

质量保障

模型使用 @JsonSerializable(checked: true, includeIfNull: false)，字符串/非空列表默认值自动补齐（响应模型）
Request/Response/Enums/Parameters 分类生成，分页模型避免重复定义
生成器提供基本语法校验与类型推断，保持 Dart 命名规范（类名 PascalCase，字段 camelCase）
文档生成器输出接口统计、控制器分组与示例，辅助对齐后端文档

性能与观测

CacheManager 缓存解析结果，避免重复请求 Swagger 源
PerformanceMonitor 记录获取/解析耗时，生成流程有摘要 (SUMMARY.md)
文件写入前统一检查跳过策略，目录按需创建，减少无效 IO

📊 性能与可观测性

解析层通过 PerformanceMonitor 记录获取/解析耗时，并复用 CacheManager 结果避免重复网络请求
多文档合并时会输出模型/路径统计与覆盖提示，便于确认版本覆盖关系
生成结束会输出 SUMMARY.md 与控制台摘要，包含控制器、路径、模型数量
文件写入前的跳过策略减少无意义的 IO，提升重复生成时的稳定性

🎯 应用场景

适用项目类型

企业级 Flutter 应用: 大量 API 接口，需要标准化管理
多人协作项目: 需要统一的代码风格和开发规范
快速迭代项目: API 变更频繁，需要快速同步
微服务架构: 多个服务的 API 需要统一管理

团队规模

小型团队 (2-5人): 提升开发效率，减少重复工作
中型团队 (5-20人): 统一开发标准，提升协作效率
大型团队 (20+人): 企业级管理，确保代码质量和一致性

🚀 核心优势

1. 开发效率提升

自动化程度: 95% 的 API 代码自动生成
开发时间节省: 减少 70%+ 的 API 相关开发时间
错误率降低: 类型相关错误减少 90%+

2. 代码质量保证

类型安全: 编译时类型检查，避免运行时错误
标准一致: 统一的代码风格和命名规范
文档同步: API 文档与代码自动保持同步

3. 维护成本降低

变更响应: API 变更响应时间从小时级降到分钟级
技术债务: 标准化代码结构，易于维护和扩展
团队协作: 统一的开发流程和代码规范

📈 发展路线

当前版本 (v2.1.x)

✅ dev dependency 场景的 CLI 入口与可执行别名
✅ 多 Swagger 顺序合并与版本化 API 输出
✅ Tag 过滤、忽略策略、BaseResult/BasePageResult 导入配置
✅ 示例项目与基础测试脚本（tests/）

后续计划

🔄 提升自动化测试覆盖与生成结果校验
🔄 完善配置校验与错误提示体验
🔄 持续同步 README/示例与最新生成逻辑

🤝 社区与支持

文档资源

贡献方式

提交功能前运行 dart run swagger_generator_flutter generate --all 以及必要的 build_runner
在 Issue/PR 中附上配置片段与最小示例（可参考 example/）
变更生成规则时同步更新 README 与 docs/

项目维护者: Max 最后更新: 2025-11-09 文档版本: v2.1

9.9 KiB Raw Blame History Unescape Escape

XY Swagger Generator - 项目概览

📋 项目简介

🎯 设计目标

🏗️ 核心架构

架构层次

模块关系图（简化）

模块职责与核心类

代码生成流程（详细）

最近重构变更（摘自 check_list）

核心组件

1. 命令与配置

2. 解析器 (Parsers)

3. 验证器 (Validators)

4. 生成器 (Generators)

5. 工具类 (Utils)

🔧 技术特性

生成行为

质量保障

性能与观测

📊 性能与可观测性

🎯 应用场景

适用项目类型

团队规模

🚀 核心优势

1. 开发效率提升

2. 代码质量保证

3. 维护成本降低

📈 发展路线

当前版本 (v2.1.x)

后续计划

🤝 社区与支持

文档资源

贡献方式

9.9 KiB

Raw Blame History