161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# Changelog
|
||
|
||
All notable changes to this project will be documented in this file.
|
||
|
||
## [3.2.0] - 2026-01-12
|
||
|
||
### 🎉 新特性
|
||
|
||
#### 模型类名前缀支持
|
||
- ✅ **支持配置文件配置**：在 `generator_config.yaml` 中配置 `models.class_prefix`，自动为生成的模型类添加前缀。
|
||
- ✅ **性能优化**：为 `ConfigRepository` 添加缓存机制，减少磁盘 I/O。
|
||
## [3.1.0] - 2025-11-24
|
||
|
||
### 🎉 新特性
|
||
|
||
#### 枚举键名映射支持
|
||
- ✅ **支持 OpenAPI 扩展字段**：通过 `x-enum-varnames` 和 `x-enum-descriptions` 生成有意义的枚举键名和注释
|
||
- ✅ **支持配置文件映射**：在 `generator_config.yaml` 中配置枚举键名映射，无需后端支持
|
||
- ✅ **三级优先级系统**：配置文件映射 > Swagger 扩展字段 > 智能生成
|
||
- ✅ **完整类型支持**：支持整数枚举和字符串枚举
|
||
- ✅ **部分映射支持**：可以只配置部分枚举值，未配置的使用智能生成
|
||
|
||
#### 配置文件增强
|
||
- ✅ 新增 `generation.models.enum_key_mappings` 配置项
|
||
- ✅ 更新 `generator_config.template.yaml`，添加详细的枚举映射示例和说明
|
||
- ✅ 新增 `EnumKeyMapping` 数据类，支持枚举键名和描述配置
|
||
|
||
### 📝 文档更新
|
||
- 新增 [**枚举快速参考**](./ENUM_QUICK_REFERENCE.md) - 三种生成方式对比和快速上手
|
||
- 新增 [**枚举使用指南**](./ENUM_KEY_NAMES_USAGE.md) - 详细的使用说明、后端实现示例和常见问题
|
||
- 新增 [**枚举实现总结**](./ENUM_CONFIG_MAPPING_SUMMARY.md) - 功能实现细节和测试验证
|
||
- 新增 [**枚举配置示例**](./example/enum_config_mapping_example.yaml) - 完整的配置文件示例
|
||
- 更新 README.md，添加枚举键名映射功能说明
|
||
|
||
### 🔧 技术细节
|
||
- 修改 `lib/core/config_repository.dart`：添加 `enumKeyMappings` 解析逻辑
|
||
- 修改 `lib/core/config.dart`：暴露枚举映射配置
|
||
- 修改 `lib/pipeline/generate/impl/model/model_content_builders.dart`：实现三级优先级枚举生成
|
||
- 新增 `EnumKeyMapping` 类：封装枚举键名和描述配置
|
||
|
||
### 💡 使用场景
|
||
1. 后端支持 OpenAPI 扩展字段 → 使用 `x-enum-varnames`
|
||
2. 后端不支持扩展字段 → 使用配置文件映射
|
||
3. 需要覆盖 Swagger 定义 → 使用配置文件映射
|
||
4. 快速原型开发 → 使用智能生成（默认）
|
||
|
||
### 📚 相关资源
|
||
- [OpenAPI 扩展字段规范](https://swagger.io/docs/specification/openapi-extensions/)
|
||
- [示例 Swagger 文档](./example/swagger_enum_example.json)
|
||
- [配置文件示例](./example/enum_config_mapping_example.yaml)
|
||
|
||
---
|
||
|
||
## [3.0.0] - 2025-11-21
|
||
|
||
### Breaking changes
|
||
- Removed OptimizedRetrofitGenerator and its public export. RetrofitApiGenerator is now the sole supported generator.
|
||
|
||
### Migration
|
||
- Replace imports/usages of OptimizedRetrofitGenerator with RetrofitApiGenerator. Example:
|
||
- Before:
|
||
import 'package:swagger_generator_flutter/generators/optimized_retrofit_generator.dart';
|
||
final generator = OptimizedRetrofitGenerator(className: 'ApiService');
|
||
- After:
|
||
import 'package:swagger_generator_flutter/generators/retrofit_api_generator.dart';
|
||
final generator = RetrofitApiGenerator(
|
||
className: 'ApiService',
|
||
useRetrofit: true,
|
||
useDio: true,
|
||
splitByTags: true,
|
||
versionedApi: true,
|
||
);
|
||
|
||
### Docs
|
||
- Updated README and docs to reference RetrofitApiGenerator only.
|
||
|
||
|
||
## [2.1.1] - 2025-11-05
|
||
|
||
### 🎉 新特性
|
||
|
||
#### 作为 dev_dependencies 支持
|
||
- ✅ 添加 `executables` 配置，支持作为 dev_dependencies 在其他项目中使用
|
||
- ✅ 可通过 `dart run swagger_generator_flutter generate` 命令执行
|
||
- ✅ 支持从使用者项目根目录读取 `generator_config.yaml` 配置文件
|
||
- ✅ 新增完整的使用指南 `USAGE_AS_DEV_DEPENDENCY.md`
|
||
- ✅ 提供配置文件模板 `generator_config.template.yaml`
|
||
|
||
### 📝 文档更新
|
||
- 更新 README.md，新增 "作为 dev_dependencies 使用" 章节
|
||
- 新增详细的集成指南，包含 CI/CD 示例
|
||
- 提供完整的工作流程说明
|
||
|
||
### 🔧 配置优化
|
||
- 更新 `pubspec.yaml` 描述信息
|
||
- 添加可执行命令映射配置
|
||
|
||
---
|
||
|
||
## [2.1.0] - 2025-11-03
|
||
|
||
### 🎉 主要新特性
|
||
|
||
#### 多版本 API 支持
|
||
- 支持解析多个 Swagger 文档 URL（v1/v2/v3...）
|
||
- API 文件按版本自动分目录（api/v1/、api/v2/）
|
||
- V1 版本类名保持简洁（不加后缀，如 `MobileManagerApi`）
|
||
- V2+ 版本类名添加版本号后缀（如 `MobileManagerApiV2`）
|
||
- ApiClient 提供清晰的版本化访问器
|
||
|
||
#### 模型智能分类
|
||
- 新增 `ModelUsageType` 枚举（request/response/common/unknown）
|
||
- 自动分析 Swagger paths 判定模型实际用途
|
||
- 精确区分请求参数和返回结果
|
||
|
||
#### 目录结构优化
|
||
- `api_models/enums/` - 枚举类型
|
||
- `api_models/request/` - 请求模型
|
||
- `api_models/result/` - 响应模型
|
||
- `api_models/parameters/` - 查询参数类
|
||
- 每个子目录自动生成 `index.dart` 便于导入
|
||
|
||
### ✨ 改进
|
||
|
||
#### 默认值处理
|
||
- 响应模型的 List 类型自动添加 `@JsonKey(defaultValue: [])`
|
||
- 请求模型不添加默认值，避免影响后端接收
|
||
- 更安全的 null 值处理
|
||
|
||
#### 导入策略
|
||
- API 文件统一使用 `import '../../api_models/index.dart'`
|
||
- 利用 Dart tree-shaking，不影响应用大小
|
||
- 简化导入管理，提高可维护性
|
||
|
||
### 🔧 配置变更
|
||
- `SwaggerConfig.swaggerJsonUrls` 现在支持多个 Swagger 文档 URL
|
||
- 移除了单独的 `swaggerJsonUrl` 配置项
|
||
|
||
### 📝 文档
|
||
- 新增 `CANCELTOKEN_USAGE_GUIDE.md` - CancelToken 使用指南
|
||
- 新增 `CHANGELOG_CANCELTOKEN.md` - CancelToken 功能变更日志
|
||
|
||
---
|
||
|
||
## [2.0.1] - 2025-10-XX
|
||
|
||
### 改进
|
||
- 性能优化和 bug 修复
|
||
- 代码质量提升
|
||
|
||
---
|
||
|
||
## [2.0.0] - 2025-09-XX
|
||
|
||
### 重大变更
|
||
- 项目重构
|
||
- 支持 Retrofit
|
||
- 优化代码生成逻辑
|
||
|
||
|