Release 0.2.0

Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.
2026-07-31 16:47:39 +08:00
parent ea93f09154
commit 454e6c51d7
56 changed files with 14506 additions and 491 deletions
@@ -0,0 +1,254 @@
+# 配置参考
+
+[English](../CONFIGURATION.md) | [简体中文](CONFIGURATION.md)
+
+`koi_swagger_parser` 使用 YAML 配置。完整注释示例见
+[koi_swagger_parser.example.yaml](../../koi_swagger_parser.example.yaml)。
+未知字段会产生 `config.unknown_key`；非法 scalar 类型和非法组合会在 OpenAPI
+解析前报错。
+
+## 查找顺序与路径语义
+
+未传入 `--config` 时，加载器按以下顺序在工作目录查找：
+
+1. `koi_swagger_parser.yaml`
+2. `koi_swagger_parser.yml`
+3. `generator_config.yaml`
+4. `generator_config.yml`
+
+所有相对 OpenAPI 文件 source、输出目录和显式 manifest 路径都以所选配置文件的
+目录为基准。未找到配置文件时，以命令调用目录为基准。
+
+显式传入配置文件且未指定 `--cwd` 时，其目录也会成为 build_runner 使用的宿主
+项目工作目录。`--cwd` 可覆盖命令工作目录，但不会重新解释配置中的相对路径。
+HTTP(S) source URL 保持 URL 语义。
+
+## 顶层字段
+
+| 字段 | 类型 | 必填 | 默认值 |
+|---|---|---:|---|
+| `input` | map | 是 | 无 |
+| `output` | map | 否 | 见下文 |
+| `generation` | map | 否 | 见下文 |
+| `formatting` | map | 否 | 见下文 |
+
+必须至少配置一个启用的 `input.swagger_urls` 项。
+
+## `input`
+
+### `input.swagger_urls`
+
+类型：字符串或 source 对象的列表。默认：空，会报错。
+
+```yaml
+input:
+  swagger_urls:
+    - ./openapi.yaml
+    - url: https://example.com/openapi.json
+      enabled: true
+    - url: ./experimental.yaml
+      enabled: false
+```
+
+source 对象字段：
+
+| 字段 | 类型 | 必填 | 默认值 | 含义 |
+|---|---|---:|---|---|
+| `url` | string | 是 | 无 | 本地路径、file URL 或 HTTP(S) URL |
+| `enabled` | boolean | 否 | `true` | 是否参与生成 |
+
+source 按配置顺序处理。多个根文档会确定性合并；operation 冲突报错，component
+冲突会确定性改名并产生诊断。
+
+## `output`
+
+| 字段 | 类型 | 默认值 | 含义 |
+|---|---|---|---|
+| `base_dir` | string path | `./lib/src` | 生成代码公共根 |
+| `api_dir` | string path | `<base_dir>/api` | API 输出根 |
+| `models_dir` | string path | `<base_dir>/api_models` | model 输出根 |
+| `included_tags` | string list | 未设置 | 包含匹配 tag 的 operation |
+| `excluded_tags` | string list | 未设置 | 排除匹配 tag 的 operation |
+| `included_paths` | string list | 未设置 | 包含匹配的 OpenAPI path |
+| `excluded_paths` | string list | 未设置 | 排除匹配的 OpenAPI path |
+| `included_operations` | string list | 未设置 | 包含匹配 operation |
+| `excluded_operations` | string list | 未设置 | 排除匹配 operation |
+| `included_models` | string list | 未设置 | 把匹配 schema 加为生成根 |
+| `excluded_models` | string list | 未设置 | 排除匹配 model |
+| `split_by_tags` | boolean | `true` | 按 operation tag 拆分 API 文件 |
+| `extract_version_from_url` | boolean | `false` | 尝试从 source URL 提取分组版本 |
+| `clean_stale_files` | boolean | `true` | 安全删除不再生成的自有文件 |
+| `skip_if_unchanged` | boolean | `true` | spec、config 和内容未变时跳过写入 |
+| `manifest_path` | string path | `<project>/.dart_tool/koi_swagger_parser/manifest.json` | 所有权/hash manifest |
+
+过滤项支持：
+
+- 精确字符串；
+- `*`、`?`、`**` glob；
+- `regex:<expression>`，使用 Dart 正则语法。
+
+同一值同时匹配 include/exclude 时，exclude 优先；相同字面量同时出现在两边会
+产生 warning。若保留的 operation 依赖被排除 model，生成会失败，不会输出无法
+编译的客户端。
+
+stale cleanup 仅处理旧 manifest 记录、仍位于当前 API/model 根、且内容仍匹配
+旧 hash 的文件。manifest 应放在生成的 API/model 根之外。
+
+## `generation.preset`
+
+| 字段 | 类型 | 默认值 | 可选值 |
+|---|---|---|---|
+| `name` | string | `koi_flutter` | `koi_flutter` |
+
+当前版本只有一个 renderer preset：Dio + Retrofit API 和
+Freezed/json_serializable model。
+
+## `generation.api`
+
+| 字段 | 类型 | 默认值 | 可选值/含义 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 生成 API |
+| `use_retrofit` | boolean | `true` | 启用 API 时必须为 `true` |
+| `cancel_token_support` | boolean | `false` | 添加 Dio `CancelToken` 参数 |
+| `response_mode` | string | `body` | `body`、`http_response` |
+| `binary_response_mode` | string | `bytes` | `bytes`、`stream` |
+
+`generation.api.enabled: true` 要求 `generation.models.enabled: true`，因为
+当前 Retrofit renderer 会导入生成的 model index。
+
+### `generation.api.client`
+
+| 字段 | 类型 | 默认值 | 含义 |
+|---|---|---|---|
+| `class_name` | string | `ApiClient` | 生成的 client class 名 |
+| `file_name` | string | `api_client` | 生成的 client 文件名 |
+
+值会转换为安全的 Dart identifier/file name。
+
+### `generation.api.response_wrapper`
+
+| 字段 | 类型 | 默认值 | 可选值/含义 |
+|---|---|---|---|
+| `mode` | string | `passthrough` | `passthrough`、`external_generic` |
+| `success_data_field` | string | `data` | envelope 中的成功 payload 字段 |
+| `detect_standard_envelope` | boolean | `true` | 检测配置的 code/message/data 风格 envelope |
+| `external_generic.import` | string | 无 | `external_generic` 模式必填 |
+| `external_generic.class_name` | string | `BaseResult` | 外部 generic wrapper 类型 |
+
+```yaml
+generation:
+  api:
+    response_wrapper:
+      mode: external_generic
+      success_data_field: data
+      detect_standard_envelope: true
+      external_generic:
+        import: package:your_network/your_network.dart
+        class_name: BaseResult
+```
+
+兼容字段 `generation.api.base_result_import` 会在未显式设置 mode 时选择
+`external_generic`，class name 为 `BaseResult`。新配置应优先使用结构化写法。
+
+## `generation.models`
+
+| 字段 | 类型 | 默认值 | 含义 |
+|---|---|---|---|
+| `enabled` | boolean | `true` | 生成 model |
+| `class_prefix` | string | `Koi` | 生成 model 名称前缀 |
+| `default_non_nullable_list_to_empty` | boolean | `true` | 符合条件的非空 list 默认使用空 list |
+| `enum_unknown_fallback` | boolean | `false` | 生成并使用 `unknown` enum 成员 |
+| `enum_unknown_default_case` | boolean | `false` | 上一字段的兼容别名 |
+
+### `generation.models.json_serializable`
+
+| 字段 | 类型 | 默认值 |
+|---|---|---|
+| `checked` | boolean | `true` |
+| `explicit_to_json` | boolean | `true` |
+| `include_if_null` | boolean | `false` |
+
+这些值会在适用场景传给生成的 json_serializable annotation。
+
+### Enum 映射
+
+支持 list 和 map 两种写法：
+
+```yaml
+generation:
+  models:
+    enum_mappings:
+      OrderStatus:
+        - value: pending
+          name: waitingForPayment
+          description: 等待付款
+        - value: done
+          name: completed
+      Priority:
+        1: low
+        2:
+          name: high
+          description: 需要关注
+```
+
+外层 key 是 OpenAPI enum/schema 名称。wire `value` 可以是 string、number 或
+boolean；`name` 必须是非空 Dart 成员名；`description` 可选。
+
+兼容字段 `enum_key_mappings` 接受同样结构。两个字段映射同一 enum value 时，
+`enum_mappings` 优先并产生 warning。vendor extension 优先级见
+[README 的 Enum 映射](../../README.zh-CN.md#enum-映射)。
+
+## `generation.mappings`
+
+所有 mapping 段默认都是空 map。
+
+| 字段 | 结构 | 含义 |
+|---|---|---|
+| `models` | `schema: DartName` | 重命名生成的 component model |
+| `properties` | `schema: {wireProperty: dartField}` | 重命名指定 schema 的属性 |
+| `parameters` | `operation: {wireParameter: dartParameter}` | 重命名指定 operation 的参数 |
+| `operations` | `operation: dartMethod` | 重命名 operation |
+| `schemas` | `schema: type-or-object` | 使用外部 Dart 类型，不生成该 schema |
+| `types` | `openapiType[:format]: type-or-object` | 映射 OpenAPI scalar/type pattern |
+| `imports` | `DartType: packageImport` | 为映射后的 Dart 类型提供 import |
+
+operation key 可以是 `operationId` 或 `METHOD /path`。type mapping 先尝试
+`type:format`，再尝试 `type`。
+
+type-or-object 可以是 Dart 类型字符串，也可以是：
+
+```yaml
+type: UuidValue
+import: package:uuid/uuid_value.dart
+```
+
+同一 mapping scope 内，两个 source name 不能指向同一个 Dart 名。相同 schema
+不能同时出现在 `models` 和 `schemas`。同一个 Dart 类型不能解析出冲突 import。
+这些组合都会报配置错误。
+
+## `formatting`
+
+| 字段 | 类型 | 默认值 | 可选值/含义 |
+|---|---|---|---|
+| `run_dart_fix` | boolean | `false` | 对本轮改变的主生成文件执行 `dart fix --apply` |
+| `run_dart_format` | boolean | `true` | 格式化本轮改变的主生成文件 |
+| `run_build_runner` | boolean | `false` | 主文件写入后运行 build_runner |
+| `build_runner_mode` | string | `build` | `build`、`watch` |
+| `delete_conflicting_outputs` | boolean | `true` | 向 build_runner 传入 `--delete-conflicting-outputs` |
+
+CLI `--watch` 会在非 dry-run 生成后启动 build_runner watch，不受配置 mode
+限制。watch 是长驻流程，适合交互式开发，不适合一次性 CI job。
+
+## 组合规则
+
+加载器会强制以下关系：
+
+- API 和 model 不能同时关闭；
+- API 当前依赖 model；
+- API 当前要求 `use_retrofit: true`；
+- `external_generic` response wrapper 需要非空 import；
+- 未知 preset、enum/response/build-runner mode 会报错；
+- 非法 filter 正则会报错；
+- mapping target/import 冲突会报错。
+
+稳定 code 和处理方式见[诊断参考](DIAGNOSTICS.md)。