koi_swagger_parser/doc/MIGRATION.md

# Migrating from swagger_generator_flutter

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

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](../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:

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

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

Recommended form:

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

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

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

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

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

For interactive development:

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

```bash
dart run swagger_generator_flutter generate --all
```

New:

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