koi_swagger_parser/doc/MIGRATION.md

Migrating from swagger_generator_flutter

English | Chinese (Simplified)

This guide covers migration from the generator_config.yaml conventions used by swagger_generator_flutter. Perform the migration in the consuming Dart/Flutter repository; no local machine path is assumed.

Recommended sequence

1. Preserve the old generated output on a separate branch.
2. Copy koi_swagger_parser.example.yaml and migrate only sources, output roots, and response wrapping first.
3. Set clean_stale_files: false for the first run and use --dry-run.
4. Generate into temporary directories and compare API signatures, JSON keys, and imports.
5. Migrate enum, naming, and custom type mappings.
6. Run build_runner, dart analyze, and the host project's tests.
7. After reviewing the output, switch to the final directories and enable clean_stale_files: true.

Settings that carry over

Previous field	New field or behavior
input.swagger_urls	Same name; strings/objects, enabled, local paths, and HTTP(S) sources are supported
output.base_dir/api_dir/models_dir	Same names
output.included_tags/excluded_tags	Same names, with glob and regular-expression support
output.split_by_tags	Same name
generation.api.client.class_name/file_name	Same names
generation.api.cancel_token_support	Same name
generation.api.base_result_import	Compatibility input; selects external_generic with BaseResult
generation.models.class_prefix	Same name
generation.models.json_serializable.*	Same names
generation.models.enum_key_mappings	Still accepted; migrate toward enum_mappings
formatting.run_dart_format	Same name

An existing enum mapping does not need to be rewritten immediately:

generation:
  models:
    enum_key_mappings:
      TaskType:
        - value: 1
          name: spotCheck
          description: Spot check

When both fields map the same wire value, enum_mappings wins. The generator also recognizes x-enumNames, x-enum-varnames, and x-enum-values.

Settings that need rewriting

Response wrapper

Previous form:

generation:
  api:
    base_result_type: BaseResult
    base_result_import: package:app/network/base_result.dart

Recommended form:

generation:
  api:
    response_wrapper:
      mode: external_generic
      detect_standard_envelope: true
      success_data_field: data
      external_generic:
        import: package:app/network/base_result.dart
        class_name: BaseResult

There is no automatic one-to-one migration for base_page_result_type/base_page_result_import. Prefer an accurate pagination schema in OpenAPI. To reuse an existing type, use generation.mappings.schemas, or keep the server envelope in passthrough mode.

Type and import mappings

Previous top-level type_mapping and imports values were global. The new configuration groups validated mappings under generation.mappings:

generation:
  mappings:
    schemas:
      Money:
        type: Money
        import: package:money2/money2.dart
    types:
      string:uuid:
        type: UuidValue
        import: package:uuid/uuid_value.dart
      string:date-time: DateTime
    imports:
      UuidValue: package:uuid/uuid_value.dart

Type lookup tries type:format before type. A schemas entry means that the schema is completely supplied by an external type and no Dart model is generated for it.

Ignored directories and files

The previous ignored_directories and ignored_files settings skipped files after rendering and could leave APIs referencing missing models. Replace them with semantic source filters:

output:
  excluded_paths:
    - /api/v1/legacy/**
  excluded_operations:
    - regex:^internal
  excluded_models:
    - Legacy*

If a retained operation depends on an excluded model, generation fails with filter.required_model_excluded. There is intentionally no setting that arbitrarily drops a rendered file.

Version extraction

Paths such as /api/v1/ and /v2/ are grouped automatically. To also try extracting a version from the source URL:

output:
  extract_version_from_url: true

The previous custom generation.api.version_extraction.pattern/default_version setting has no one-to-one equivalent. A URL extraction failure produces a diagnostic and falls back to path-based grouping.

build_runner

The previous workflow commonly ran build_runner separately. It can now be part of generation:

formatting:
  run_dart_format: true
  run_build_runner: true
  build_runner_mode: build
  delete_conflicting_outputs: true

For interactive development:

dart run koi_swagger_parser generate --watch

Watch mode is long-running and should not be used for a one-shot CI job.

Previous settings that are not read

These fields produce a config.unknown_key warning:

• generator.name/version/author/copyright;
• input.validate_schema/strict_mode;
• output.api_file_suffix/model_file_suffix;
• generation.api.use_dio/parser/method_naming;
• generation.models.class_naming/field_naming/use_const_constructor;
• top-level validation.on_error/on_warning;
• top-level generic import ordering/grouping settings.

The new generator uses structured errors for cases that would break wire semantics or compilation. It does not provide a warn/ignore override for those errors. Unsupported constructs that can be omitted safely, such as callbacks and links, produce warnings.

Generated-code differences to review

• A schema with read-only/write-only fields can become FooRequest and FooResponse.
• An optional field whose schema disallows null still uses a nullable Dart argument to represent absence, together with disallowNullValue; explicit JSON null is rejected.
• A root object with properties plus additionalProperties flattens extras into the JSON root.
• A default response is never treated as successful.
• Complex parameter styles can introduce a public transport adapter and a private Retrofit delegate.
• API methods can return HttpResponse<T>; binary output can use bytes or a stream.
• Generated enums include wire conversion, and unknown fallback uses an internal sentinel wire value.
• Stale files are removed only through manifest ownership; a user-modified stale file is preserved.

CLI comparison

Previous:

dart run swagger_generator_flutter generate --all

New:

dart run koi_swagger_parser generate --all
dart run koi_swagger_parser generate --dry-run --verbose

Previous --api, --models, --docs, and CLI tag overrides are not retained. Use generation.*.enabled and output filters. The current generator does not emit a separate API documentation site.

Acceptance checklist

• The dry run has no error diagnostics.
• Enum wire values and Dart member names match the previous contract.
• Request/response directional models contain the expected fields.
• Cookie, query, and path serialization produces equivalent requests.
• Error and default responses are not decoded as successful responses.
• External custom types have correct imports and JSON conversion.
• dart run build_runner build --delete-conflicting-outputs succeeds.
• dart analyze and host-project tests pass.
• The second generation reports lifecycle.unchanged_skipped.
• Removing an operation deletes only unmodified files owned by the manifest.

For every available backend fixture, compare runtime serialization in addition to generated source text.