koi_swagger_parser/doc/zh-CN/COMPATIBILITY.md

兼容性

English | 简体中文

本矩阵只描述当前实现和自动化测试已覆盖的行为。

• 支持：已经实现并测试；
• 部分支持：仅支持“边界”列出的子集；
• 不支持：生成前产生诊断，或 warning 后明确忽略。

文档、引用与合并

能力	状态	边界
OpenAPI 3.0.x / 3.1.x	支持	JSON/YAML；客户端生成所需常见 Schema Object 子集
Swagger/OpenAPI 2.0	不支持	openapi.unsupported_version error
本地 $ref	支持	各 component 分组的 JSON Pointer
相对文件 / file URL $ref	支持	相对当前引用文档解析
HTTP(S) $ref	支持	单次运行缓存、依赖追踪和循环诊断
外部 component 重名	支持	确定性改名并 warning
多 root source	支持	确定性 merge；component/operation 冲突诊断
unresolved $ref	支持诊断	error，不静默转换成 dynamic
callbacks / webhooks	不支持	warning，不生成反向调用 client
Link Object	不支持	openapi.links_not_supported warning

当前不是完整 JSON Schema 2020-12 实现。$defs 作为生成根、 if/then/else、not、contains、dependentSchemas 和 unevaluated property/item 语义不在当前契约中。

Schema 与 model

能力	状态	边界
object / array / map	支持	递归容器和 inline schema
properties + additionalProperties	支持	extra entry 在 JSON 根 round trip
string/number/integer/bool/date/date-time	支持	format 可由 type mapping 覆盖
enum	支持	string、number、boolean wire value；inline/component
enum 成员名映射	支持	配置及常见 x-enum extension
enum unknown fallback	支持	可配置 JsonKey.unknownEnumValue 输出
required / nullable / absent	支持	反序列化区分缺失和不允许 null；普通 Freezed 字段不保留 presence 历史
readOnly / writeOnly	支持	必要时生成 request/response directional variant
allOf	支持	合并 object property、required 和 additional property
discriminator oneOf/anyOf	支持	local 或已归一化 object branch
无 discriminator oneOf/anyOf	部分支持	primitive/container/object；重叠 oneOf 匹配会拒绝
custom schema/type/format	支持	external import；宿主代码负责 JSON 转换契约
constraint metadata	部分支持	保留 description/doc comment；不生成 runtime validator
presence/dirty tracking	不支持	无 Kiota 风格 backing store

HTTP wire 语义

能力	状态	边界
path/query/header/cookie parameter	支持	type、required/default 和 wire name
matrix / label / simple	支持	校验 location/style 组合
form / spaceDelimited / pipeDelimited / deepObject	支持	校验 query/cookie 组合
explode / allowReserved	支持	Retrofit 无法表达时生成 transport adapter
Parameter Object content	部分支持	必须恰有一个 media type
JSON / +json request body	支持	required body 和 null-to-absent
text request body	支持	typed @Body
multipart/form-data	支持	binary、primitive、array 和 structured JSON part
application/x-www-form-urlencoded	支持	typed field；复杂 encoding 使用 adapter
binary upload	支持	Uint8List
binary download	支持	Uint8List 或 Dio ResponseBody stream
XML / Protobuf / 任意 custom codec	不支持	content-type error，不生成不安全 decoder

Response、server 与 security

能力	状态	边界
多个 2xx / 204 / 2XX	支持	确定性 primary response；不同 JSON type 可 warning 后变成 Object?
default / 4xx / 5xx	支持	保留 error model/IR metadata；不作为 success
response header	支持	status、type、required flag 和 description
raw response metadata	支持	response_mode: http_response
binary + JSON 混合 success media	支持诊断	单个 Retrofit 方法无法安全 decode 时 error
root/path/operation server	支持	server variable default/enum 校验；preferred server 成为 client default
多 server runtime 切换	部分支持	保留 metadata；不生成环境选择 UI
API key / Bearer / Basic	支持 metadata	生成 scheme/operation requirement；凭证由宿主 interceptor/provider 提供
OAuth2 / OpenID / mutual TLS	部分支持	仅 scheme/scope metadata；不生成完整授权流程
security OR/AND requirement	支持	list 项是 OR；同一 map 项中的 scheme 是 AND

生成与生命周期

能力	状态	边界
Retrofit + Freezed	支持	当前版本唯一完整 renderer
passthrough / external generic wrapper	支持	可配置标准 envelope 检测
model/property/parameter/operation mapping	支持	collision 校验和安全 identifier
schema/type/import mapping	支持	递归 Dart List/Map type expression
tag/path/operation/model filter	支持	exact、glob 和 regex:
dry-run	支持	报告 would-write/would-delete
Dart fix / format	支持	仅本轮改变的主生成文件
build_runner build/watch	支持	在配置的宿主项目目录执行
unchanged skip	支持	spec/config/content 和实际文件 SHA-256
stale cleanup	支持	manifest ownership、root containment、用户修改保护
concurrent generation lock	支持	manifest 旁的操作系统 exclusive lock
external template / plugin renderer	不支持	IR/preset 已分层，但无公开 renderer SPI
完整 SDK package scaffold	不支持	在已有项目内生成 API/model

验证覆盖

仓库测试覆盖：

• parser、IR、renderer 和 lifecycle 阶段；
• OpenAPI 3.0 YAML、OpenAPI 3.1 JSON/FastAPI fixture；
• enum/命名 mapping、parameter wire style、response、schema 语义、security 和 external/cyclic ref；
• reviewed SHA-256 golden；
• 生成到临时 Dart package，随后运行 build_runner、analysis 和 runtime test。

矩阵中的“支持”不代表超出所列边界的完整 OpenAPI/JSON Schema conformance。 引入新的 schema corpus 时，应先用最小 fixture 和 dry-run 验证。

诊断含义和处理方式见诊断参考。