koi_swagger_parser/doc/CONFIGURATION.md

Configuration reference

English | Chinese (Simplified)

koi_swagger_parser reads YAML configuration. The complete commented example is 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.

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:

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:

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

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 for stable codes and remediation guidance.