koi_swagger_parser/doc/zh-CN/CONFIGURATION.md

# 配置参考

[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)。