koi_swagger_parser/doc/CONFIGURATION.md

# Configuration reference

[English](CONFIGURATION.md) | [Chinese (Simplified)](zh-CN/CONFIGURATION.md)

`koi_swagger_parser` reads YAML configuration. The complete commented example
is [koi_swagger_parser.example.yaml](../koi_swagger_parser.example.yaml).
Unknown keys produce `config.unknown_key`; invalid scalar types and invalid
combinations produce errors before OpenAPI parsing starts.

## Discovery and path semantics

Without `--config`, the loader searches the working directory in this order:

1. `koi_swagger_parser.yaml`
2. `koi_swagger_parser.yml`
3. `generator_config.yaml`
4. `generator_config.yml`

All relative OpenAPI file sources, output directories, and explicit manifest
paths are resolved against the directory containing the selected
configuration file. If no configuration file is found, they are resolved
against the invocation directory.

When an explicit configuration file is supplied and `--cwd` is omitted, its
directory is also the host-project working directory used for build_runner.
`--cwd` overrides that command working directory but does not rebase relative
configuration paths. HTTP(S) source URLs remain URLs.

## Top-level sections

| Field | Type | Required | Default |
|---|---|---:|---|
| `input` | map | yes | none |
| `output` | map | no | defaults below |
| `generation` | map | no | defaults below |
| `formatting` | map | no | defaults below |

At least one enabled `input.swagger_urls` entry is required.

## `input`

### `input.swagger_urls`

Type: list of strings or source objects. Default: empty, which is an error.

```yaml
input:
  swagger_urls:
    - ./openapi.yaml
    - url: https://example.com/openapi.json
      enabled: true
    - url: ./experimental.yaml
      enabled: false
```

Each source object accepts:

| Field | Type | Required | Default | Meaning |
|---|---|---:|---|---|
| `url` | string | yes | none | Local path, file URL, or HTTP(S) URL |
| `enabled` | boolean | no | `true` | Whether the source participates |

Sources are processed in configuration order. Multiple roots are merged
deterministically; conflicting operations are errors and conflicting
components are renamed with diagnostics.

## `output`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `base_dir` | string path | `./lib/src` | Common generated-code base |
| `api_dir` | string path | `<base_dir>/api` | Generated API root |
| `models_dir` | string path | `<base_dir>/api_models` | Generated model root |
| `included_tags` | string list | unset | Include matching operation tags |
| `excluded_tags` | string list | unset | Exclude matching operation tags |
| `included_paths` | string list | unset | Include matching OpenAPI paths |
| `excluded_paths` | string list | unset | Exclude matching OpenAPI paths |
| `included_operations` | string list | unset | Include matching operations |
| `excluded_operations` | string list | unset | Exclude matching operations |
| `included_models` | string list | unset | Add matching schemas as roots |
| `excluded_models` | string list | unset | Exclude matching models |
| `split_by_tags` | boolean | `true` | Split API files by operation tag |
| `extract_version_from_url` | boolean | `false` | Try to derive grouping version from a source URL |
| `clean_stale_files` | boolean | `true` | Safely remove obsolete owned files |
| `skip_if_unchanged` | boolean | `true` | Skip writes when spec, config, and content are unchanged |
| `manifest_path` | string path | `<project>/.dart_tool/koi_swagger_parser/manifest.json` | Ownership/hash manifest |

Filter entries accept:

- an exact string;
- `*`, `?`, and `**` glob syntax;
- `regex:<expression>`, using Dart regular-expression syntax.

An exclusion wins when the same value matches include and exclude rules.
Putting the same literal in both lists produces a warning. If an included
operation requires an excluded model, generation fails instead of emitting an
uncompilable client.

Stale cleanup is limited to files recorded in the previous manifest, inside
the current API/model roots, with content that still matches the previous
hash. Keep the manifest outside the generated API/model roots.

## `generation.preset`

| Field | Type | Default | Allowed values |
|---|---|---|---|
| `name` | string | `koi_flutter` | `koi_flutter` |

The current release has one renderer preset: Dio + Retrofit APIs and
Freezed/json_serializable models.

## `generation.api`

| Field | Type | Default | Allowed values / meaning |
|---|---|---|---|
| `enabled` | boolean | `true` | Generate API files |
| `use_retrofit` | boolean | `true` | Must remain `true` when API generation is enabled |
| `cancel_token_support` | boolean | `false` | Add Dio `CancelToken` parameters |
| `response_mode` | string | `body` | `body`, `http_response` |
| `binary_response_mode` | string | `bytes` | `bytes`, `stream` |

`generation.api.enabled: true` requires
`generation.models.enabled: true`, because the current Retrofit renderer
imports the generated model index.

### `generation.api.client`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `class_name` | string | `ApiClient` | Generated client class name |
| `file_name` | string | `api_client` | Generated client file stem |

Values are converted to safe Dart identifiers/file names.

### `generation.api.response_wrapper`

| Field | Type | Default | Allowed values / meaning |
|---|---|---|---|
| `mode` | string | `passthrough` | `passthrough`, `external_generic` |
| `success_data_field` | string | `data` | Envelope field containing the success payload |
| `detect_standard_envelope` | boolean | `true` | Detect configured code/message/data-style envelopes |
| `external_generic.import` | string | none | Required in `external_generic` mode |
| `external_generic.class_name` | string | `BaseResult` | External generic wrapper type |

Example:

```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
```

The legacy `generation.api.base_result_import` key selects
`external_generic` with class name `BaseResult` when no explicit mode is set.
Prefer the structured form for new configurations.

## `generation.models`

| Field | Type | Default | Meaning |
|---|---|---|---|
| `enabled` | boolean | `true` | Generate model files |
| `class_prefix` | string | `Koi` | Prefix for generated model names |
| `default_non_nullable_list_to_empty` | boolean | `true` | Default eligible non-nullable list values to an empty list |
| `enum_unknown_fallback` | boolean | `false` | Generate and use an `unknown` enum member |
| `enum_unknown_default_case` | boolean | `false` | Legacy alias for `enum_unknown_fallback` |

### `generation.models.json_serializable`

| Field | Type | Default |
|---|---|---|
| `checked` | boolean | `true` |
| `explicit_to_json` | boolean | `true` |
| `include_if_null` | boolean | `false` |

These values are forwarded to generated json_serializable annotations where
applicable.

### Enum mappings

Both list and map forms are accepted:

```yaml
generation:
  models:
    enum_mappings:
      OrderStatus:
        - value: pending
          name: waitingForPayment
          description: Waiting for payment
        - value: done
          name: completed
      Priority:
        1: low
        2:
          name: high
          description: Requires attention
```

The outer key is the OpenAPI enum/schema name. A wire `value` may be a string,
number, or boolean; `name` must be a non-empty Dart member name.
`description` is optional.

`enum_key_mappings` accepts the same shape for compatibility. When both fields
map the same enum value, `enum_mappings` wins and a warning is emitted. See
[Enum mappings in the README](../README.md#enum-mappings) for vendor-extension
precedence.

## `generation.mappings`

All mapping sections default to an empty map.

| Field | Shape | Meaning |
|---|---|---|
| `models` | `schema: DartName` | Rename generated component models |
| `properties` | `schema: {wireProperty: dartField}` | Rename properties within one schema |
| `parameters` | `operation: {wireParameter: dartParameter}` | Rename parameters within one operation |
| `operations` | `operation: dartMethod` | Rename operations |
| `schemas` | `schema: type-or-object` | Reuse an external Dart type instead of generating the schema |
| `types` | `openapiType[:format]: type-or-object` | Map an OpenAPI scalar/type pattern |
| `imports` | `DartType: packageImport` | Supply imports for mapped Dart types |

Operation keys may be an `operationId` or `METHOD /path`. Type mappings try
`type:format` before `type`.

A type-or-object value is either a Dart type string or:

```yaml
type: UuidValue
import: package:uuid/uuid_value.dart
```

Within one mapping scope, two source names cannot target the same Dart name.
The same schema cannot appear in both `models` and `schemas`. A Dart type
cannot resolve to conflicting imports. These combinations are configuration
errors.

## `formatting`

| Field | Type | Default | Allowed values / meaning |
|---|---|---|---|
| `run_dart_fix` | boolean | `false` | Run `dart fix --apply` on changed primary generated files |
| `run_dart_format` | boolean | `true` | Format changed primary generated files |
| `run_build_runner` | boolean | `false` | Run build_runner after the primary write |
| `build_runner_mode` | string | `build` | `build`, `watch` |
| `delete_conflicting_outputs` | boolean | `true` | Pass `--delete-conflicting-outputs` to build_runner |

The CLI `--watch` flag starts build_runner watch after a non-dry generation,
regardless of the configured build_runner mode. Watch mode is long-running and
is intended for interactive development rather than one-shot CI jobs.

## Combination rules

The loader enforces these relationships:

- API and model generation cannot both be disabled.
- API generation currently requires model generation.
- API generation currently requires `use_retrofit: true`.
- `external_generic` response wrapping requires a non-empty import.
- Unknown preset and enum/response/build-runner mode values are errors.
- Invalid filter regular expressions are errors.
- Mapping target/import conflicts are errors.

See [Diagnostics](DIAGNOSTICS.md) for stable codes and remediation guidance.