koi_swagger_parser/doc/zh-CN/CONFIGURATION.md

配置参考

English | 简体中文

koi_swagger_parser 使用 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 对象的列表。默认：空，会报错。

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 类型

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 两种写法：

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 映射。

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 类型字符串，也可以是：

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 和处理方式见诊断参考。