mr.koi
454e6c51d7
Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.
114 lines
6.3 KiB
Markdown
114 lines
6.3 KiB
Markdown
# 兼容性
|
||
|
||
[English](../COMPATIBILITY.md) | [简体中文](COMPATIBILITY.md)
|
||
|
||
本矩阵只描述当前实现和自动化测试已覆盖的行为。
|
||
|
||
- **支持**：已经实现并测试；
|
||
- **部分支持**：仅支持“边界”列出的子集；
|
||
- **不支持**：生成前产生诊断，或 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 验证。
|
||
|
||
诊断含义和处理方式见[诊断参考](DIAGNOSTICS.md)。
|