koi_swagger_parser/doc/zh-CN/CHANGELOG.md

更新日志

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

English | 简体中文

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。