# Changelog

All notable changes to this project will be documented in this file.

## [3.3.0] - 2026-01-31

### 🎉 新特性

#### CancelToken 请求取消支持
- ✅ **可选配置**：在 `generator_config.yaml` 中通过 `generation.api.cancel_token_support: true` 启用
- ✅ **自动参数注入**：为每个生成的 API 方法自动添加 `@CancelRequest() CancelToken? cancelToken` 参数
- ✅ **完全可选**：CancelToken 参数可选，不影响现有代码
- ✅ **Retrofit 兼容**：生成的代码与 retrofit_generator 完全兼容

### 📝 文档更新
- 新增 [**CancelToken 使用指南**](./CANCELTOKEN_USAGE_GUIDE.md) - 详细配置说明和使用示例
- 新增 [**CancelToken 变更日志**](./CHANGELOG_CANCELTOKEN.md) - 功能实现细节

### 🔧 技术细节
- 修改 `lib/core/config_repository.dart`：添加 `cancelTokenSupport` getter
- 修改 `lib/pipeline/generate/impl/retrofit_api/api_parameters.dart`：在 `_generateParameters()` 中添加 CancelToken 参数
- 更新 `generator_config.template.yaml`：添加 `cancel_token_support` 配置项说明
- 新增 `test/cancel_token_support_test.dart`：10 个单元测试验证功能正确性

### 💡 使用示例
```yaml
# generator_config.yaml
generation:
  api:
    cancel_token_support: true
```

生成的代码：
```dart
Future<Result> getUsers({
  @Query('page') int? page,
  @CancelRequest() CancelToken? cancelToken,
});
```

---

## [3.2.1] - 2026-01-12

### 🐛 修复

#### 模型类名前缀逻辑修复
- ✅ **强制添加前缀**：修复了当类名已包含前缀时不重复添加前缀的逻辑，确保 `SubjectInfo` 配置前缀 `S` 后生成 `SSubjectInfo`。
- ✅ **测试接口暴露**：为 `ConfigRepository` 添加 `setCachedConfig` 接口以便于测试。
## [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
- 优化代码生成逻辑