# 更新日志

本文件记录此 package 的重要变更。

[English](../../CHANGELOG.md) | [简体中文](CHANGELOG.md)

## 0.2.0 - 2026-07-31

### 破坏性变更

- 主 library 不再导出 `DartType`、`ModelSpec`、`ApiOperation`、
  `GeneratedFile`、`GeneratedBundle` 等 parser IR 实现类型；请改用
  `KoiSwaggerParser` 及其文档化的 `GenerationResult`；
- 不再导出 `KoiSwaggerConfigLoader`；程序化加载配置请改用
  `KoiSwaggerConfig.load()`。

### 新增

- 结构化配置、OpenAPI、过滤和生命周期诊断；error 不再静默生成已知错误代码；
- local、relative、file 和 HTTP(S) `$ref` 解析，包括缓存、循环检测、依赖
  追踪、外部 component bundling 和确定性多 source 冲突处理；
- `enum_mappings`、兼容字段 `enum_key_mappings`、常见 `x-enum` 扩展、描述和
  可选 unknown enum fallback；
- model、property、parameter、operation、schema、type 和 import 映射及冲突校验；
- OpenAPI path、query、header、cookie 参数序列化，包括已支持的 matrix、label、
  form、simple、spaceDelimited、pipeDelimited、deepObject、explode 和
  `allowReserved` 组合；
- JSON、text、multipart、form-urlencoded 和 binary upload，以及 bytes/stream
  download；
- 多成功响应、204、`2XX`、`default`、错误模型、响应头和 `HttpResponse<T>` 模式；
- required、nullable、absent 语义、readOnly/writeOnly 投影，以及根级
  `properties` + `additionalProperties` round trip；
- `allOf`、discriminator union，以及已支持的 primitive、container、object
  `oneOf`/`anyOf`；
- server variables、security schemes 和 operation OR/AND security metadata；
- tag、path、operation、model 的精确、glob 和正则过滤；
- 带锁 manifest、spec/config/content SHA-256、未变化跳过、安全 stale cleanup、
  原子写入和 dry-run 变更计划；
- 内置 build_runner build/watch 集成、reviewed golden、OpenAPI 3.0/3.1 fixture
  和临时生成包验证；
- 英文 canonical 文档与完整简体中文镜像，以及配置、兼容性、诊断和迁移参考。

### 变更

- `GenerationResult.writtenFiles` 现在只包含实际写入文件；`generatedFiles` 包含
  完整目标集合；dry-run 使用 `wouldWriteFiles` 和 `wouldDeleteFiles`；
- 显式传入配置文件且未设置 `workingDirectory`/`--cwd` 时，配置文件目录成为
  宿主项目工作目录；
- `default` response 不再视为成功；XML、Protobuf 和没有安全 decoder 的其他
  response media type 会产生诊断；
- `dart fix` 和 `dart format` 仅处理本轮改变的主生成文件。
- 所有非测试 Dart 声明均在不使用文件级排除的情况下满足
  `public_member_api_docs`，包括内部 IR 和 lifecycle 类型。

### 修复

- 使 `formatting.run_dart_fix` 和 `output.extract_version_from_url` 真正生效；
- 避免 Dio/Retrofit `Headers` import 冲突、Freezed custom `toJson` 缺失，以及
  parameter、field、method mapping 碰撞。
- lifecycle manifest 记录的生成器版本已与 package `0.2.0` 同步。

## 0.1.0 - 2026-06-02

- 首次发布 `koi_swagger_parser`；
- 支持常见 OpenAPI 3.1/FastAPI 解析、Koi 风格 Retrofit API 生成和 Freezed
  模型生成；
- 支持兼容读取旧版 `generator_config.yaml`。